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Google Android 官 方 培训 教程 
中 文 版 


Android 入 门 基础 : 从 这 里 开始 
建立 第 一 个 App 
创建 Android 项 目 
执行 Android 程 序 
建立 简单 的 用 户 界 面 
启动 其 他 的 Activity 
添加 ActionBar 
建立 ActionBar 
Js JmActiondz 42 
自 定义 ActionBar 的 风格 
ActionBarf/ % s 2 & 
兼容 不 同 的 设备 
适 配 不 同 的 语言 
适 配 不 同 的 屏幕 
适 配 不 同 的 系统 版 本 
管理 Activity 的 生命 周期 
启动 与 销毁 Activity 
暂停 与 恢复 Activity 
停止 与 重启 Activity 
重新 创建 Activity 
使 用 Fragment 建 立 动态 的 UI 
创建 一 个 Fragment 
建立 灵活 动态 的 UI 
Fragments 之 间 的 交互 
数据 保存 
保存 到 Preference 
保存 到 文件 
保存 到 数据 库 
与 其 他 应 用 的 交互 


E ak 


Intent 的 发 送 
接收 Activity 返 回 的 结果 


Intent 过 滤 


Android 分 享 操作 


分 享 简单 的 数据 
给 其 他 App 发 送 简单 的 数据 
接收 从 其 他 App 返 回 的 数据 
给 ActionBar 增 加 分 享 功能 


分 享 文件 


获取 文件 信息 

使 用 NFC 分 享 文件 
发 送 文 件 给 其 他 设备 
接收 其 他 设备 的 文件 


Android 多 媒体 


管理 音频 播放 
控制 音量 与 音频 播放 
管理 音频 焦点 
兼容 音频 输出 设备 
拍照 
简单 的 拍照 
简单 的 录像 
控制 相机 硬件 
打印 
打印 照片 
打印 HTML 文 档 
打印 自 定义 文档 


Android 图 像 与 动画 


高 效 显示 Bitmap 
高 效 加 载 大 图 
FUIR A Bitmap 
缓存 Bitmap 


管理 Bitmap 的 内 存 
在 UI 上 显示 Bitmap 
使 用 OpenGL ES 显示 图 像 
建立 OpenGL ES 的 环境 
定义 Shapes 
绘制 Shapes 
运用 投影 与 相机 视图 
添加 移动 
响应 触摸 事件 
添加 动画 
View 间 渐变 
使 用 ViewPager 实 现 屏 幕 滑动 
展示 Card 翻 转动 画 
缩放 View 
布局 变更 动画 
Android 网 络 连接 与 云 服务 
无 线 连 接 设备 
使 用 网 络 服务 发 现 
使 用 WiFi 建 立 P2P 连 接 
使 用 WiFi P2P 服 务 
执行 网 络 操作 
连接 到 网 络 
管理 网 络 的 使 用 情况 
解析 XML 数据 
传输 数据 时 避免 消耗 大 量 电量 
优化 下 载 以 高 效 地 访问 网 络 
最 小 化 定期 更 新 造成 的 影响 
重复 的 下 载 是 宛 余 的 
根据 网 络 连 接 类 型 来 调整 下 载 模式 
云 同步 
使 用 备份 API 
使 用 Google Cloud Messaging 
解决 云 同步 的 保存 冲突 


使 用 Sync Adapter 传 输 数 据 
创建 Stub 授 权 器 
创建 Stub Content Provider 
创建 Sync Adpater 
执行 Sync Adpater 
使 用 Volley 执 行 网 络 数据 传输 
发 送 简单 的 网 络 请 求 
建立 请 求 队列 
创建 标准 的 网 络 请 求 
实现 自 定义 的 网 络 请 求 
Android 联 系 人 与 位 置信 息 
Android 联 系 人 信息 
获取 联系 人 列表 
获取 联系 人 详情 
使 用 Intents 修 改 联 系 人 信息 
显示 联系 人 头像 
Android 位 置信 息 
获取 最 后 可 知 位 置 
获取 位 置 更 新 
显示 位 置地 址 
创建 和 监视 地 理 围 栏 
Android 可 穿戴 应 用 
赋 子 Notification 可 穿戴 特性 
创建 Notification 
在 Notifcation 中 接收 语音 输入 
为 Notification 添 加 显示 页 面 
以 Stack 的 方式 显示 Notifications 
创建 可 穿戴 的 应 用 
创建 并 运行 可 穿戴 应 用 
创建 自 定义 的 布局 
添加 语音 功能 
打包 可 穿戴 应 用 
通过 蓝牙 进行 调试 
自 


创建 自 定 义 的 UI 


定义 Layouts 

创建 Card 

创建 List 

创建 2D Picker 
创建 确认 界面 
退出 全 屏 的 Activity 


党 


发 送 并 同步 数据 


访问 可 穿戴 数据 层 
同步 数据 单元 
传输 资源 

发 送 与 接收 消息 
处 理 数据 层 的 事件 


e m A 


设计 表盘 
建 表盘 服务 
绘制 表盘 
在 表盘 上 显示 信息 
提供 配置 Activity 
定位 常见 的 问题 
优化 性 能 和 电池 使 用 时 间 


位 置 检 测 
Android TV 应 用 


创 


创 


建 TV 应 用 


创建 TV 应 用 的 第 一 
处 理 TV 硬 件 部 分 
建 TV 的 布局 文件 
创建 TV 的 导航 栏 


建 TV 播 放 应 用 


创建 目录 浏览 器 
提供 一 个 Card 视 图 
创建 详情 页 

显示 正在 播放 卡片 


帮助 用 户 在 TV 上 探索 内 容 


TV 上 的 推荐 内 容 
使 得 TV App 能 够 被 搜索 
使 用 TV 应 用 进行 搜索 
创建 TV 游戏 应 用 
创建 TV 直播 应 用 
TV Apps Checklist 
Android 企 业 级 应 用 
Ensuring Compatibility with Managed Profiles 
Implementing App Restrictions 
Building a Work Policy Controller 
Android 交 互 设 计 
设计 高 效 的 导航 
规划 屏幕 界面 与 他 们 之 间 的 关系 
为 多 种 大 小 的 屏幕 进行 规划 
提供 向 下 和 横向 导航 
提供 向 上 和 历史 导航 
综合 : 设计 样 例 App 
实现 高 效 的 导航 
使 用 Tabs 创 建 Swipe 视 图 
创建 抽 层 导航 
提供 向 上 的 导航 
提供 向 后 的 导航 
实现 向 下 的 导航 
通知 提示 用 户 
建立 Notification 
当局 动 Activity 时 保留 导航 
更 新 Notification 
使 用 BigView 风 格 
显示 Notification 进 度 
增加 搜索 功能 
建立 搜索 界面 
保存 并 搜索 数据 
保持 向 下 兼容 
使 得 你 的 App 内 容 可 被 Google 搜 索 
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为 App 内 容 开 局 深度 链接 
为 索引 指定 App 内 容 
Android- mitt 
为 多 屏幕 设计 
兼容 不 同 的 屏幕 大 小 
兼容 不 同 的 屏幕 密度 
实现 可 适应 的 UI 
创建 自 定 义 View 
创建 自 定义 的 View 类 
实现 自 定义 View 的 绘制 
使 得 View 可 交互 
优化 自 定义 View 
创建 向 后 兼容 的 U| 
抽象 新 的 APIs 
代理 至 新 的 APls 
使 用 昌 的 APls 实 现 新 API| 的 效果 
使 用 版 本 敏感 的 组 件 
实现 辅助 功能 
开发 辅助 程序 
开发 辅助 服务 
管理 系统 U| 
淡化 系统 Bar 
隐藏 系统 Bar 
隐藏 导航 Bar 
全 屏 沉浸 式 应 用 
响应 UI 可 见 性 的 变化 
创建 使 用 Material Design 的 应 用 
开始 使 用 Material Design 
使 用 Material 的 主题 
创建 Lists 与 Cards 
定义 Shadows 与 Clipping 视 图 
使 用 Drawables 


自 定 义 动画 


维护 兼容 性 
Android 用 户 输入 

使 用 触摸 手势 

仿 测 常用 的 手势 

跟踪 手势 移动 

滚动 手势 动画 

处 理 多 点 触 控 手势 

拖 搜 与 缩放 

管理 ViewGroup 中 的 触摸 事件 
处 理 键 瘟 输入 

指定 输入 法 类 型 

处 理 输入 法 可 见 性 

支持 键盘 导航 

处 理 按键 动作 
支持 游戏 控制 器 

处 理 控制 器 输入 动作 


在 不 同 的 Android 系统 版 本 支持 控制 器 


支持 多 个 控制 器 
Android 后 台 任 务 
在 IntentService 中 执行 后 台 任 务 
创建 IntentService 
发 送 工作 任务 到 IntentService 
报告 后 侣 任务 执行 状态 
使 用 CursorLoader 在 后 人 台 加 载 数 据 
使 用 CursorLoader 执 行 查询 任务 
处 理 CursorLoader 查 询 的 结果 
管理 设备 的 唤醒 状态 
保持 设备 的 唤醒 
制定 重复 定时 的 任务 
Android' 性 能 优化 
管理 应 用 的 内 存 
代码 性 能 优化 建议 
提升 Layout 的 性 能 
优化 layout 的 层级 
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使 用 include 标 签 重 用 layouts 
按 需 加 载 视图 
使 得 ListView 浓 动 顺畅 
优化 电池 寿命 
监测 电量 与 充电 状态 
判断 与 监测 Docking 状 态 
判断 与 监测 网 络 连 接 状 态 
根据 需要 操作 Broadcast 接 受 者 
多 线程 操作 
在 一 个 线程 中 执行 一 段 特 定 的 代码 
为 多 线程 创建 线程 池 
居 动 与 停止 线程 池 中 的 线程 
与 UI 线程 通信 
避免 出 现 程 序 无 响应 ANR 
JNI 使 用 指南 
优化 多 核 处 理 器 (SMP) 下 的 Android 程 序 
Android 安 全 与 隐私 
Security Tips 
使 用 HTTPS 与 SSL 
为 防止 SSL 漏 洞 而 更 新 Security 
使 用 设备 管理 条 例 增强 安全 性 
Android 测 试 程序 
测试 你 的 Activity 
建立 测试 环境 
创建 与 执行 测试 用 例 
测试 Ul 组件 
创建 单元 测试 
创建 功能 测试 
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Android 官 方 培训 课程 中 文 版 (v0.9.7) 


hudgoip | 





Google Android A K 7€ 20124F a9 HY 4& 7-3X T Android Training 板 块 - 
http://developer.android.com/training/index.html > 3& RE ze Žž J Android & A F 2 85) 46 4 3E 
料 。 我 们 通过 Github 发 起 开源 协作 翻译 的 项 目 ， 完 成 中 文 版 的 输出 ， 欢 迎 大 家 传阅 学 习 | 文 
章 中 难免 会 有 很 多 写 的 不 对 不 好 的 地 方 ， 欢 迎 读者 加 入 此 协作 项 目 ， 进 行 纠 错 ， 为 完善 这 份 
教程 贡献 一 点 力量 ! 


Github 托 管 主 页 


https://github.com/kesenhoo/android-training-course-in-chinese 


请 读者 点 击 Star 进 行 关注 并 支持 ! 


` M NES 
在 线 阅读 
http://hukai.me/android-training-course-in-chinese/index.html 


更 新 记录 


v0.9.7 - 2016/11/04 
v0.9.6 - 2016/05/22 
e v0.9.5 - 2015/12/15 
e v0.9.4 - 2015/06/11 
e v0.9.3 - 2015/05/18 
e v0.9.2 - 2015/03/30 


e v0.9.1 - 2015/03/14 
e v0.9.0 - 2015/03/09 
e v0.8.0 - 2015/02/12 
e v0.7.0 - 2014/11/30 
e v0.6.0 - 2014/11/02 
e v0.5.0 - 2014/10/18 
e v0.4.0 - 2014/09/11 
e v0.3.0 - 2014/08/31 
e v0.2.0 - 2014/08/14 
e v0.1.0 - 2014/08/05 


参与 方式 


你 可 以 选择 以 下 的 方式 帮忙 修改 纠正 这 份 教程 (推荐 使 用 方法 1) 


1. 通过 在 线 阅读 课程 的 页 面 ， 找 到 Github 仓 库 对 应 的 章节 文件 ， 直 接 在 线 编辑 修改 提交 即 
可 。 

2. 在 线 阅读 的 文章 底部 留言 ， 提 出 问题 与 修改 意见 ， 我 会 抽 时 间 及 时 处 理 。 

3.， 写 邮件 给 发 起 人 : 胡 凯 ， 邮 箱 是 kesenhoo at gmail.com， 邮 件 内 容 注 明 需要 纠正 的 章节 
段落 位 置 ， 并 给 出 纠正 的 建议 。 


致谢 


发 起 这 个 项 目 之 后 ， 得 到 很 多 人 的 支持 ， 有 经 验 丰富 的 Android 开 发 者 ， 也 有 刚 接触 Android 的 
爱好 者 。 他 们 有 些 已 经 上 班 ， 有些 还 是 学 生 ， 有 些 在 国内 ， 还 有 的 在 国外 ! 感谢 所 有 参与 或 
者 关注 这 个 项 目的 小 伙伴 ! 


下 面 是 参与 翻译 的 小 伙伴 (Github ID 按照 课程 结构 排序 ) : 


0 1 2 


(Qyuanfentiank789 (Qvincent4j @Lin-H 
@kesenhoo @fastcome1985 @jdneo 

(QXizhiXu @naizhengtan @spencer198711 
@penkzhou @wangyachen @wly2014 
@fastcome1985 @riverfeng @xrayzh 

@KOST @Andrwyw (Qzhaochungi 
@lltowgq @allenlsy @AllenZheng1991 
@pedant @craftsmanBai @huanglizhuo 
@Roya @awong1900 @dupengwei 

0:10 1:10 2:10 


(Q X XR AC] PU * HEE : http://hukai.me > Github : https://github.com/kesenhoo * 4 
博 : http://weibo.com/kesenhoo 


还 有 众多 参与 纠 错 校正 的 同学 名 字 就 不 一 一 列举 了 ， 谢 谢 所 有 关注 这 个 项 目的 小 伙伴 ! 特别 
感谢 安 草 巴士 社区 ， 爱 开发 社区 ， 码 农 周刊 对 项 目的 宣传 ! 


License 


本 站 作品 由 https:/github.com/kesenhoo/android-training-course-in-chinese 创 作 ， 采 用 知识 共 
享 署名 - 非 商 业 性 使 用 -相同 方式 共享 4.0 国际 许可 协议 进行 许可 。 
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Android 入 门 基础 : 从 这 里 开始 


编写 :kesenhoo - 原文 :http://developer.android.com/training/index.html 
欢迎 来 到 为 Android 开 发 者 准备 的 培训 项 目 。 在 这 里 你 会 找到 一 系列 的 课程 ， 这 些 课 程 会 演示 
你 如 何 使 用 可 重用 的 代码 来 完成 特定 的 任务 。 所 有 的 课程 分 为 若干 不 同 的 小 组 。 你 可 以 通过 
左边 的 导航 来 查看 。 
第 1 章节 :“ 从 这 里 开始 "， 教 你 Android 应 用 开发 的 最 基本 的 知识 。 如 果 你 是 一 个 Android 应 用 
开发 的 新 手 ， 你 应 该 按照 顺序 学 习 完 下 面 的 课程 : 
建立 你 的 第 一 个 App(Building Your First App) 


在 你 安装 Android SDK 之 后 ， 从 这 节 课 开始 学 习 Android 应 用 开发 的 基础 知识 。 


兼容 不 同 的 设备 (Supporting Different Devices) 


学 习 给 应 用 提供 可 选择 的 资源 文件 来 实现 如 何 使 用 一 个 APK 来 使 得 你 的 应 用 能 够 在 不 同 的 设 
备 上 获取 到 最 佳 的 用 户 体验 。 


使 用 Fragment 建 立 动态 的 UI(Building a Dynamic UI with 
Fragments) 


学 习 如 何 为 你 的 应 用 建立 一 套 足 够 灵活 的 Ul， 这 套 UI 能 够 在 大 屏幕 的 设备 上 显示 多 个 UI| 组 
件 ， 在 小 屏幕 的 设备 上 呈现 紧凑 的 UI 组 件 。 这 使 得 你 能 够 为 手机 与 平板 只 建立 同一 个 APK © 


数据 保存 (Saving Data) 


学 习 如 何在 设备 上 保存 数据 。 无 论 这 些 数据 是 临时 的 文件 ， 应 用 下 载 的 资源 ， 用 户 的 多 媒体 
数据 ， 结 构 化 的 数据 还 是 其 他 。 


与 其 他 应 用 的 交互 (Interacting with Other Apps) 


学 习 如 何 利用 其 他 已 经 存在 应 用 的 既 有 功能 来 执行 更 进一步 的 用 户 任务 。 例 如 拍照 或 者 在 地 
图 上 查看 某 个 地 址 。 


使 用 系统 权限 (Working with System Permissions) 


学 习 声 明 你 的 app 需 要 访问 在 它 “ 沙 箱 " 之 外 的 功能 和 资源 ， 以 及 如 何在 运行 时 申请 这 些 特权 。 


Android 入 门 基础 : 从 这 里 开始 
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建立 第 一 个 App 


编写 :yuanfentiank789 - 原 
X :http://developer.android.com/training/basics/firstapp/index.html 


欢迎 开始 Android 应 用 开发 之 旅 ! 


本 章节 我 们 将 学 习 如 何 建立 我 们 的 第 一 个 Android 应 用 程序 。 我 们 将 学 到 如 何 使 用 Android 
Studio 创 建 一 个 Android 项 目 并 运行 该 应 用 程序 的 可 调试 版 本 。 此 外 ， 我 们 还 将 学 习 到 一 些 
Android 应 用 程序 设计 的 基础 知识 ， 包 括 如 何 创建 一 个 简单 的 用 户 界面 ， 以 及 处 理 用 户 输入 。 


开始 本 章节 学 习 之 前 ， 我 们 要 确保 已 经 安装 了 开发 环境 。 我 们 需要 : 
1 下载 并 安装 Android Studio. 


2 使 用 SDK Manager (可 以 设置 g.cn:80 作 为 SDK 人 代理， 实现 免 翻 墙 更 新 SDK) 下 载 最 新 的 
SDK tools#-platforms ° 


Note: 虽然 这 一 系列 的 培训 课程 中 的 大 多 数 章 节 都 预期 你 会 使 用 Android Studio 3t 47 + 
发 ， 但 某 些 开 发 操作 还 是 可 以 通过 SDK tools 中 提供 的 命令 来 实现 的 。 


本 章节 通过 向 导 的 方式 来 逐步 创建 一 个 小 型 的 Android 应 用 ， 通 过 这 些 步 骤 来 教 给 我 们 一 些 
Android 开 发 的 基本 概念 ， 因 此 你 很 有 必要 按照 教程 的 步骤 来 学 习 操 作 。 


开始 学 


创建 Android 项 目 


编写 :yuanfentiank789- 原 
文 :http://developer.android.com/training/basics/firstapp/creating-project.html 


一 个 Android 项 目 包含 了 所 有 构成 Android 应 用 的 源 代码 文件 。 
本 小 节 介 绍 如 何 使 用 Android Studio 或 者 是 SDK Tools 中 的 命令 行 来 创建 一 个 新 的 项 目 。 


Note: 在 此 之 前 ， 我 们 应 该 已 经 安装 了 Android SDK， 如 果 使 用 Android Studio 开 发 ， 应 
该 确保 已 经 安装 了 Android Studio ° $M) > 1 7.147% Installing the Android SDK 按 照 向 导 


完成 安装 步骤 。 


使 用 Android Studio 创 建 项 目 


1. 使 用 Android Studio®] Androidi A > Æ 4 Android Studio ° 


e 如 果 我 们 还 没有 用 Android Studio 打 开 项 目 ， 会 看 到 欢迎 页 ， 点 击 Start a new Android 
Studio project ° 

e 如 果 已 经 用 Android Studio 打 开 了 项 目 ， 点 击 菜单 中 的 File， 选 择 New Project 来 创建 一 个 
新 的 项 目 。 


2. 在 弹出 的 窗口 (Configure your new project) 中 填 入 内 容 ， 点 击 Next。 按 照 如 下 的 值 进 
行 填写 会 使 得 后 续 的 操作 步骤 不 容易 出 差错 。 


。 Application Name 此 处 填写 想 呈现 给 用 户 的 应 用 名 称 ， 此 处 我 们 使 用 "My First App” ° 

e Company domain 包 名 限定 符 ，Android Studio 会 将 这 个 限定 符 应 用 于 每 个 新 建 的 
Android 项 目 ， 此 处 使 用 "example.com"。 

e Package Name 是 应 用 的 包 命 名 空间 ( 同 Java 的 包 的 概念 ) ， 该 包 名 在 同一 Android 系 统 
上 所 有 已 安装 的 应 用 中 具有 唯一 性 ， 由 包 名 限定 符 而 定 。 

。 Project location 操作 系统 存放 项 目的 路 径 。 


3. Æ Select the form factors your app will run on 7 4 Phone and Tablet ° 


4. Minimum SDK, 选择 API 15: Android 4.0.3 (IceCreamSandwich). Minimum Required 

SDK 表 示 我 们 的 应 用 支持 的 最 低 Android 版 本 ， 为 了 支持 尽 可 能 多 的 设备 ， 我 们 应 该 设置 为 能 
支持 你 应 用 核心 功能 的 最 低 API 版 本 。 如 果 某 些 非 核心 功能 仅 在 较 高 版 本 的 API 支 持 ， 你 可 以 
只 在 支持 这 些 功 能 的 版 本 上 开启 它们 (参考 兼容 不 同 的 系统 版 本 ), 此 处 采用 默认 值 即 可 。 


5. 不 要 义 选 其 他 选项 (TV, Wear, and Glass) ， 点 击 Next. 


6. 在 Add an activity to Mobile 窗口 选择 Empty Activity ， 点 击 Next. 


7. 在 Customize the Activity 窗口 保持 默认 设置 。 
8. 点 击 Finish 完 成 创建 。 


刚 创建 的 Android 项 目 是 一 个 基础 的 Hello World 项目， 包含 一 些 默 认 文件 ， 我 们 花 一 点 时 间 看 
看 最 重要 的 部 分 : 


app/res/layout/activity main.xml 


这 是 刚才 用 Android Studio 创 建 项 目 时 新 建 的 Activity 对 应 的 xml 布 局 文件 ， 按 照 创建 新 项 目的 
流程 ，Android Studio 会 同时 展示 这 个 文件 的 文本 视图 和 图 形 化 预览 视图 ， 该 文件 包含 一 些 默 
认 设 置 和 一 个 显示 内 容 为 “Hello world!" $5 TextView;o € ° 


app/java/com.example.myfirstapp/MainActivity.java 


A Android Studio 创 建新 项 目 完成 后 ， 可 在 Android Studio 看 到 该 文件 对 应 的 选项 卡 ， 选 中 该 
选项 卡 ， 可 以 看 到 刚 创建 的 Activity 类 的 定义 。 编 译 并 运行 该 项 目 后 ，Activity 启 动 并 加 载 布局 
文件 activity_main.xml， 显 示 一 条 文本 "Hello world!" 


app/manifest/AndroidManifest .xml 


manifest 文 件 描述 了 项 目的 基本 特征 并 列 出 了 组 成 应 用 的 各 个 组 件 ， 接 下 来 的 学 习 会 更 深入 了 
解 这 个 文件 并 添加 更 多 组 件 到 该 文件 中 。 


app/build.gradle 


Android Studiot Jf] Gradle 编译 运行 Android 工 程 . 工程 的 每 个 模块 以 及 整个 工程 都 有 一 个 
build.gradle 文 件 。 通 常 你 只 需要 关注 模块 的 build.gradle 文 件 ， 该 文件 存放 编译 依赖 设置 ， 包 
括 defaultConfig 设 置 : 


。 compiledSdkVersion 是 我 们 的 应 用 将 要 编译 的 目标 Android 版 本 ， 此 处 默认 为 你 的 SDK 已 
安装 的 最 新 Android 版 本 (目前 应 该 是 4.1 或 更 高 版 本 ， 如 果 你 没有 安装 一 个 可 用 Android 版 
本 ， 就 要 先 用 SDK Manager 来 完成 安装 )， 我 们 仍然 可 以 使 用 较 老 的 版 本 编译 项 目 ， 但 把 
该 值 设 为 最 新 版 本 ， 可 以 使 用 Android 的 最 新 特性 ， 同 时 可 以 在 最 新 的 设备 上 优化 应 用 来 
提高 用 户 体验 。 

e applicationid 创建 新 项 目 时 指定 的 包 名 。 

e minSdkVersion 创建 项 目 时 指定 的 最 低 SDK 版 本 ， 是 新 建 应 用 支持 的 最 低 SDK 版 本 。 

e targetSdkVersion 表示 你 测试 过 你 的 应 用 支持 的 最 高 Android 版 本 (同样 用 API level 表 示 ). 
当 Android 发 布 最 新 版 本 后 ， 我 们 应 该 在 最 新 版 本 的 Android 测 试 自己 的 应 用 同时 更 新 
target sdk 到 Android 最 新 版 本 ， 以 便 充 分 利用 Android 新 版 本 的 特性 。 更 多 知识 ， 请 阅读 
Supporting Different Platform Versions ° 


更 多 关于 Gradle 的 知识 请 阅读 Building Your Project with Gradle 
注意 /res 目 录 下 也 包含 了 resources 资 源 : 


drawable<density>/ 


存放 各 种 densities 图 像 的 文件 夹 ，mdpi，hdpi 等 ， 这 里 能 够 找到 应 用 运行 时 的 图 标 文件 
ic_launcher.png 


layout/ 

存放 用 户 界 面 文件 ， 如 前 边 提 到 的 activity_my.xml， 描 述 了 MyActivity 对 应 的 用 户 界面 。 
menu/ 

存放 应 用 里 定义 菜单 项 的 文件 。 

values/ 


存放 其 他 Xml 资源 文件 ， 如 string，color 定 义 。string.xml 定 义 了 运行 应 用 时 显示 的 文本 "Hello 
world!" 


要 运行 这 个 APP， 继 续 下 个 小 节 的 学 习 。 


使 用 命令 行 创 建 项 目 

如 果 没 有 使 用 Android Studio 开 发 Android 项 目 ， 我 们 可 以 在 命令 行使 用 SDK 提 供 的 tools 来 创 
建 一 个 Android 项 目 。 

1. 打开 命令 行 切换 到 SDK 根 目录 下 ; 


2. 执行 


tools/android list targets 


会 在 屏幕 上 打印 出 我 们 所 有 的 Android SDK 中 下 载 好 的 可 用 Android platforms » 4X 28 3-6 z£ 7j 
目的 目标 platform， 记 录 该 platform 对 应 的 Id， 推荐 使 用 最 新 的 platform。 我 们 仍 可 以 使 自己 的 
应 用 支持 较 老 版 本 的 platform， 但 设置 为 最 新 版 本 允许 我 们 为 最 新 的 Android 设 备 优化 我 们 的 
应 用 。 如 果 没 有 看 到 任何 可 用 的 platform， 我 们 需要 使 用 Android SDK Manager 完 成 下 载 安 
装 ， 参 见 Adding Platforms and Packages。 


3. 执行 


android create project --target «target-id» --name MyFirstApp \ 
--path <path-to-workspace>/MyFirstApp --activity MyActivity \ 
--package com.example.myfirstapp 


替换 <target-id> 为 上 一 步 记 录 好 的 Id， 替换 <path-to-workspace> 为 我 们 想 要 保存 项 目的 路 


4 
径 。 


Tip: 把 platform-tools/ 和 tools/ 添加 到 环境 变量 PATH ， 开 发 更 方便 。 


到 此 为 止 ， 我 们 的 Android 项 目 已 经 是 一 个 基本 的 “Hello World" 程 序 ， 包 含 了 一 些 默认 的 文 
件 。 要 运行 它 ， 继 续 下 个 小 节 的 学 习 。 


执行 Android 程 友 


编写 :yuanfentiank789- 原 
文 :http://developer.android.com/training/basics/firstapp/running-app.html 


通过 上 一 节 课 创建 了 一 个 Android 的 Hello World 项 目 ， 项 目 默 认 包 含 一 系列 源 文件 ， 它 让 我 们 
可 以 立即 运行 应 用 程序 。 


如 何 运行 Android 应 用 取决 于 两 件 事情 : 是 否 有 一 个 Android 设 备 和 是 否 正 在 使 用 Android 
Studio 开 发 程序 。 节 课 将 会 教 使 用 Android Studio 和 命令 行 两 种 方式 在 真实 的 android 设 备 或 
者 android 模 拟 器 上 安装 并 且 运 行 应 用 。 


uc me 
fev LAL FS Lis 
如 果 有 一 个 真实 的 Android 设 备 ， 以 下 的 步骤 可 以 使 我 们 在 自己 的 设备 上 安装 和 运行 应 用 程 
序 : 
手机 设置 


1. 把 设备 用 USB 线 连接 到 计算 机 上 。 如 果 是 在 windows 系 统 上 进行 开发 的 ， 你 可 能 还 需要 安 
装 你 设备 对 应 的 USB 了 驱动 ， 详 见 OEM USB Drivers 文档 。 
2. 开启 设备 上 的 USB 调 试 选项 。 
o 在 大 部 分 运行 Andriod3.2 或 更 老 版 本 系统 的 设备 上 ， 这 个 选项 位 于 “设置 > 应 用 程序 > 
开发 选项 "里 。 
o 在 Andriod 4.0 或 更 新 版 本 中 ， 这 个 选项 在 “设置 > 开发 人 员 选 项 "里 。 


Note: 从 Android4.2 开 始 ， 开 发 人 员 选 项 在 默认 情况 下 是 隐藏 的 ， 想 让 它 可 见 ， 可 以 去 设 
置 > 关 于 手机 ( 或 者 关于 设 tr) 点击 版 本 号 七 次 。 再 返回 有 就 能 找到 开 发 人 员 选项 了 了 o 


从 Android Studio 运 行程 序 


1 选择 项 目的 一 个 文件 ， 点 击 工具 栏 里 的 Run P 按钮 。 
2. Choose Device 窗 口 出 现时 ， 选 择 Choose a running device 单 选 框 ， 点 击 OK 。 


Android Studio 会 把 应 用 程序 安装 到 我 们 的 设备 中 并 启动 应 用 程序 。 


从 命令 行 安 装运 行 应 用 程序 


打开 命令 行 并 切换 当前 目录 到 Andriod 项 目的 根 目 录 ， 在 debug 模 式 下 使 用 Gradle 编 译 项 目 ， 
使 用 gradle 脚 本 执行 assembleDebug 编 译 项 目 ， 执 行 后 会 在 build/ 目 录 下 生成 MyFirstApp- 
debug.apk ° 


Windows 操 作 系 统 下 ， 执 行 : 
gradlew.bat assembleDebug 


Mac OS 或 Linux 系 统 下 


$ chmod +x gradlew 
$ ./gradlew assembleDebug 


编译 完成 后 在 app/ 目 录 生 成 apk。 
Note: chmod 命 令 是 给 gradlew 增 加 执行 权限 ， 只 需要 执行 一 次 


确保 Android SDK 里 的 platform-tools/ 路 径 已 经 添加 到 环境 变量 PATH 中 ， 执 行 : 


adb install bin/MyFirstApp-debug.apk 


在 我 们 的 Android 设 备 中 找到 MyFirstActivity， 点 击 打开 。 


在 模拟 器 上 运行 


无 论 是 使 用 Android Studio 还 是 命令 行 ， 在 模拟 器 中 运行 程序 首先 要 创建 一 个 Android Virtual 
Device (AVD) ° AVD 是 对 Android # A 器 的 配置 ， 可 以 让 我 们 模拟 不 同 的 设备 。 


创建 一 个 AVD: 
1. 启动 Android Virtual Device Manager (AVD Manager) 的 两 种 方式 : 


* 用 Android Studio, **Tools > Android > AVD Manager**, 或 者 点 击 工具 栏 里 面 Android Virtual D 
evice Manager! [image] (avd-manager -studio.png) : 
* 在 命令 行 窗口 中 ， 把 当前 目录 切换 到 `<sdk>/tools/” 后 执行 : 


android avd 


执行 Android 程 序 


$9 o AVD Manager 


Your Virtual Devices 


Android Studio 








Type | Name | Resolution LAPI | Target | CPU/ABI | Size on Disk | Actions | 
i Android Wear Round API 20 320 x 320: hdpi 20 Android 4.4W.2 x86 566 MB pr 
加 Nexus 6 API 21 1440 x 2560: 560dpi 21 Android 5.0 x86... 650 MB pr 
L5] ProfileNexus API 21 1080 x 1920: xxhdpi 21 Android 5.0 x86 650 MB bv 

| 十 Create Virtual Device... ) La) 





2. 在 AVD Manager 面板 中 ， 点 击 Create Virtual Device. 

3. 在 Select Hardware 窗 口 ， 选 择 一 个 设备 ， 比 如 Nexus 6， 点 击 Next 。 
选择 列 出 的 合适 系统 镜像 . 

5. 校 验 模拟 器 配置 ， 点 击 Finish 。 


更 多 AVD 的 知识 请 阅读 Managing AVDs with AVD Manager. 

AJ. Android Studio 运 行程 序 

1. 在 Android Studio 选 择 要 运行 的 项 目 ， 从 工具 栏 选择 Run P: 
2. Choose Device 窗 口 出 现时 ， 选 择 Launch emulator 单 选 框 ; 


3. 从 Android virtual device 下 拉 菜 单 选择 创建 好 的 模拟 器 ， 点 击 OK ; 


模拟 器 启动 需要 几 分 钟 的 时 间 ， 启 动 完 成 后 ， 解 锁 即 可 看 到 程序 已 经 运行 到 模拟 器 屏幕 上 


从 命令 行 安装 运行 应 用 程序 
1. 用 命令 行 编译 应 用 ， 生 成 位 于 app/build/outputs/apk/ 的 apk ; 
2. 确认 platform-tools/ 已 添加 到 PATH 环 境 变 量 ; 


3. 执行 如 下 命令 


adb install app/build/outputs/apk/MyFirstApp-debug.apk 


4. 在 模拟 器 上 找到 MyFirstApp， 并 运行 


以 上 就 是 创建 并 在 设备 上 运行 一 个 应 用 的 全 部 过 程 | 想 要 开始 开发 ， 点 击 next lesson 。 
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执行 Android 程 序 
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建立 简单 的 用 户 界 


编写 : crazypudding - 原 
X : http://developer.android.com/training/basics/firstapp/building-ui.html 


在 本 小 节 里 ， 我 们 将 学 习 使 用 Android Studio 布 局 编辑 器 创建 一 个 带 有 文本 输入 框 和 按钮 的 界 
面 。 下 一 节 课 将 学 会 使 APP 对 按钮 做 出 响应 一 ”按钮 被 按 下 时 ， 文 本 框 里 的 内 容 被 发 送 到 另 
外 一 个 Activity ° 


Android 的 图 形 用 户 界面 由 多 个 视图 (View) 和 布局 (ViewGroup) 构建 而 成 。View 是 通用 
的 Ul 窗 体 小 组 件 ， 如 : 按钮 Button) 、 文 本 框 〈Text field) ; 而 ViewGroup 则 是 用 来 控制 
子 视图 如 何 显 示 在 屏幕 上 的 不 可 见 的 容器 ， 如 : 网 格 部 件 (grid) 、 重 直列 表 部 件 〈vertical 
list) 。 














m = 


Cen 





图 1 X T ViewGroup 对 象 如 何 组 织 布 局 分 支 和 和 包含 其 他 View 对 象 。 


Android 提供 了 一 系列 对 应 于 View 和 ViewGroup 子 类 的 XML 标签 ， 大 多 数 情况 下 ， 我 们 都 
会 使 用 XML 来 定义 自己 的 Ul。 不 过 这 节 课 中 我 们 不 会 练习 XML 语法 ， 而 是 练习 使 用 Android 
Studio 的 布局 编辑 器 来 创建 布局 ， 布 局 编辑 器 通过 拖 放 View 的 方式 可 以 更 容易 的 创建 一 个 布 
Bs 


辑 E 
打开 布局 编辑 
注意 : 下 面 的 内 容 都 假定 我 们 使 用 Android Studio 2.3 或 2.3 以 上 的 版 本 并 且 通 过 之 前 的 
课程 的 内 容 创建 了 一 个 Android 项 目 。 
开始 之 前 ， 按 照 如 下 步骤 设置 好 工作 台 : 


1. 在 Android Studio 的 Project 面板 中 ， 打 开 文 件 app/res/layout/activity_main.xml ° 


2. 为 布局 编辑 器 留 出 更 多 空间 ， 通 过 选择 View > Tool windows > Project 来 关闭 Project & 


板 (或 者 点 击 Android Studio Æ 4] 4) e 按钮 ) o 


3. 如 果 编 辑 器 显示 的 是 XML 源码 ， 点 击 左下 角 Design 标签 切换 到 Design 模式 。 
4. 点 击 Show Blueprint imn. 显示 蓝图 布局 。 


5. 在 布局 中 显示 Constraints。 将 筷 标 放 在 工具 栏 中 D 5.55 nH 提示 : Hide 
Constraints (当前 为 显示 Constraints) 。 


6. 关 闭 自动 连接 功能 。 将 鼠标 放 在 工具 栏 中 4 按钮 上 会 看 到 提示 : Turn On 


Autoconnect (当前 为 关闭 状态 ) 。 


7. 点 击 工具 栏 中 Default Margins 8 按钮 并 选择 16 〈 稍 后 仍 可 以 单独 为 每 个 View 调整 间 


3B) © 


8. 点 击 工具 栏 中 Device in Editor 0 按钮 并 选择 Pixel XL 。 


以 上 操作 完成 后 ，Android Studio 窗 口 应 该 如 下 图 2 所 示 
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建立 简单 的 用 户 界 面 


左下 角 的 Component Tree 面板 显示 的 是 当前 布局 中 所 有 View 的 层级 结构 。 本 例 中 ， 根 


View 是 一 个 constraintLayout ， 其 中 只 包含 一 个 rextview 对 象 。 


IE 根据 每 个 View 和 和 与 它 平 级 的 兄弟 View 以 及 父 布 局 之 间 的 约束 来 确定 它 的 
位 置 。 通 过 这 个 方法 ， 我 们 可 以 创建 简单 或 者 复杂 但 是 层级 结构 扁平 化 的 布局 。 这 样 一 来 ， 
kien hb: 出 现 (如 图 1 展示 的 那样 ， 一 个 ViewGroup 3k & 5 —^* ViewGroup) * 
缩短 了 绘制 UI 的 时 间 。 


例如 ， 我 们 可 以 这 样 创建 布局 (如 图 3) 


e View A 距 父 布局 顶部 16dp 
e View A 距 父 布局 左边 缘 16dp 
e View B 距 View 人 右边 16dp 
e View B 5 View A 顶部 对 齐 





图 3. constraintLayout 中 两 个 View 的 位 置 


在 本 节 后 面 的 部 分 中 ， 我 们 将 实际 建立 一 个 类 似 的 布局 。 
添加 一 个 文本 框 


1. 首 先 ， 要 删除 布局 中 已 经 存在 的 View， 在 Component Tree 面板 中 选中 并 删除 
TextView ° 


2.4 X f| Palette UU CX Meque Text 分 类 ， 从 右 半 部 分 窗 格 中 拖 出 Plain Text 
并 把 它 放 到 编辑 器 中 人 靠近 布局 顶部 的 地 方 。 这 是 一 个 可 以 输入 纯 文本 的 EditText 


3. 点 击 编 辑 器 中 的 View。 可 以 看 到 ， 在 每 个 角 上 都 有 一 个 方形 的 锚 点 ， 这 是 用 来 控制 View 
的 大 小 的 ; 在 每 条 边 中 间 都 有 一 个 圆 形 销 点 ， 这 是 用 来 添加 约束 的 。 


为 了 更 准确 的 控制 这 些 锚 点 ， 可 以 通过 工具 栏 中 的 缩放 按钮 来 缩放 虚拟 Ul 界面 。 
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建立 简单 的 用 户 界面 


4. 按 住 View 顶部 的 圆 形 锚 点 ， 将 它 拖 动 到 父 布局 顶部 ， 直 到 有 吸附 效果 时 放 开 。 可 以 看 到 
View 和 父 布局 顶部 之 间 出 现 一 条 带 箭头 的 细 线 ， 这 就 是 一 个 约束 eds € View 3E By SUR 
局 顶部 16dp (因为 刚刚 设置 的 默认 值 是 16dp) 。 


5. 同 样 的 ， 在 View 的 左边 和 父 布 局 的 左边 缘 创 建 一 个 约束 。 


最 终 的 效果 应 该 如 图 4 所 示 。 
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200 


o 
o 
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图 4. 文本 框 与 父 布局 顶部 和 左边 形成 约束 


添加 一 个 按钮 

1. 同 样 的 ， 在 Palette 面板 左 侧 部 分 选中 Widgets 分 类 ， 然 后 拖 出 Button 并 放 到 编辑 器 中 靠 
近 父 布局 右上 角 的 地 方 。 

2. 在 Button 的 左 侧 与 EditText 右 侧 建立 一 个 约束 。 


3. 针 对 可 显示 文字 的 View ， 我 们 可 以 通过 在 每 个 View 的 文字 基线 之 间 建 立 约 束 从 而 使 得 它 
们 水 平 对 齐 。 在 编辑 器 中 选中 一 个 View ， 这 个 被 选中 的 View 下 方 会 出 现 一 个 Baseline 


Constraint E. 。 例 如 选中 本 例 中 的 Button > Button 里 面 会 出 现 一 个 线 状 的 锚 点 ， 将 这 
个 锚 点 拖 放 到 EditText 中 的 基线 锚 点 上 。 


现在 可 以 看 到 的 效果 如 图 5 所 示 。 
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图 5. Button X 4i] fe EditText 右 侧 以 及 彼此 的 基线 之 间 建 立 了 约束 


注意 : 我 们 也 可 以 用 Button TÈR 22A 3f 85 48 js. 束 从 而 达到 水 平 对 齐 的 目的 ， 但 是 


由 于 在 Button 内 部 是 有 一 个 padding 值 的 ， 所 以 通过 这 种 方式 建立 约束 并 不 会 盟 正 实现 
水 平 对 齐 。 


变 UI 中 显示 的 字符 串 


点 击 工具 栏 中 的 Show Design i= 以 预览 我 们 的 Ul， 可 以 看 到 EditText RU X. 
字符 串 是 “Name”，Button 默认 显示 的 字符 串 是 “Button”。 接 下 来 我 们 的 目的 ME 些 字 
AP 


1. 打 开 Project 面板 ， 然 后 打开 文件 app/res/values/strings.xml 。 


strings.xml 是 一 个 字符 串 资 源 文件 ， 我 们 应 该 把 Ul 布局 中 出 现 的 字符 串 定 义 在 这 个 文件 
中 。 相 比 于 在 布局 或 逻辑 代码 中 硬 编码 ， 这 样 在 一 个 文件 集中 管理 所 有 的 字符 囊 更 利于 字符 
囊 的 查找 、 修 改 甚 至 是 本 地 化 操作 。 


2. 点 击 右 上 角 的 Open editor 按钮 可 以 打开 Translations Editor， 在 这 个 编辑 器 中 不 仅 可 以 
增加 、 修 改 默 认 字 符 串 ， 还 能 很 好 的 管理 所 有 字符 串 的 翻译 版 本 。 

3. 点 击 左 上 角 Add Key T 按钮 为 EditText 新 增 一 个 提示 文字 (hint text) 

1. 在 Key 那 一 栏 填 入 "edit message" , 这 就 是 这 个 字符 串 的 id © 


2. 在 Default Value 7f —3£3& ^. "Enter a message" ， 这 就 是 字符 串 的 内 容 ， 会 显示 到 UI 中 。 
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3. 点 击 OK ° 

















Key: | edit message | 


Default Value: 


Resource Folder: app/src/main/res 


Vv 





图 6. 新 增 字 符 串 资源 的 对 话 杠 
4. 新 增 另 一 个 字符 串 资 源 ，Key 为 "button_send" ，Default Value 为 "Send"。 


现在 可 以 通过 点 击 标签 栏 的 activity_main.xml 返回 布局 文件 通过 以 下 步骤 为 每 个 View 设置 
相应 的 字符 串 资 源 : 


1. 在 布局 编辑 器 中 选中 EditText 对 象 ， 如 果 在 窗口 右 侧 没有 出 现 Propreties 面板 的 话 可 以 点 
击 右边 侧 边栏 中 的 Properities Vus 。 Propreties 面板 会 显示 选中 对 象 的 属性 。 

2.4 Propreties 面板 中 找到 hint 属性 ， 然 后 点 击 文本 框 右边 的 Pick a Resource 按钮 ， 
在 弹出 的 对 话 框 中 双击 edit message ° 

3. 同 样 在 EditText 的 Propreties 面板 中 删除 text 属性 的 值 (当前 值 为 "Name") 。 


4. 在 布局 编辑 器 中 选中 Button 对 象 切换 到 Button 对 应 的 Propreties 面板 ， 将 Button 的 text 
属性 值 更 换 成 id 为 "button_send" 的 字符 串 资源 。 


让 文本 输入 框 大 小 灵活 


为 了 创建 一 个 可 以 适应 不 同 大 小 的 屏幕 ， 我 们 需要 调整 EditText ， 使 得 它 可 以 在 计算 完 
Button 的 宽度 和 Margin 间距 之 后 ， 自 行 伸展 至 占有 所 有 的 剩余 宽度 
在 继续 之 前 ， 点 击 Show Blueprint imn... ， 我 们 依然 在 蓝图 模式 下 工作 。 


择 所 有 的 View 对 象 (选中 其 中 一 个 ， 按 住 Shift 并 选中 另 一 个 ) ， 和 鼠标 右 击 其 中 一 个 
View 象 ， 从 菜单 中 选择 Center Horizontally 。 


建立 简单 的 用 户 界 面 


虽然 我 们 的 目标 不 是 让 所 有 的 View 对 象 水平 居 中 ， 但 是 这 种 方法 可 以 在 这 些 View 之 间 快 速 
建立 起 一 个 约束 链 (constraint chain)。 约 束 链 是 在 两 个 或 多 个 View 对 象 之 间 形 成 的 一 个 双向 
约束 ， 它 可 以 将 这 些 View 对 象 链接 起 来 多 为 一 个 整体 进行 编排 布局 。 不 过 这 样 会 消除 View 
对 象 之 间 水 平方 向 的 间距 ， 所 以 后 面 需要 手动 更 改 。 设 置 完 约束 链 的 效果 如 下 图 : 
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2. 选 中 Button 并 打开 相应 的 Propreties 面板 ， 将 左右 margin 设置 为 16。 

3. 选 中 EditText 并 将 left margin 设置 为 16。 

4. 在 EditText 的 Propreties 面板 中 ， 点 击 图 8 中 标示 为 1 处 的 按钮 (这 是 宽度 指示 符 ) 直到 出 
现 MW Ask s 这 表示 我 们 已 经 将 EditText 的 width 属性 设置 为 Match Constraints 了 。 


"Match Constraints" 的 意思 是 View 的 宽度 受 水 平方 向 的 约束 和 间距 影响 。 因 此 ，EditText 的 
宽度 会 伸展 至 占用 所 有 剩余 的 水 平 空间 (在 计算 完 Button 的 宽度 和 Margin 问 距 之 后 ) 。 
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D 


: oF 


A 8. 设置 width 属性 值 为 "Match Constraints" 


目前 为 止 ， 我 们 已 经 完成 了 本 节 课 程 中 布局 的 所 有 内 容 。 最 终 效果 应 该 如 图 9 所 示 。 
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图 9. EditText 占有 所 有 剩余 空间 


如 果 您 的 布局 没有 达到 预期 的 效果 ， 可 以 查看 下 面 的 完整 代码 进行 对 比 (各 属性 出 现 的 顺序 
不 会 影响 布局 的 样式 ) 。 以 下 是 完整 代码 : 
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<?xml version="1.0" encoding="utf-8"?> 
<android.support.constraint.ConstraintLayout 
xmlns:android="http://schemas.android.com/apk/res/android" 
xmlins:app-"http://schemas.android.com/apk/res-auto" 
xmlns:tools-"http://schemas.android.com/tools" 
android: layout_width="match_parent" 
android: layout_height="match_parent" 
tools:context="com.example.myfirstapp.MainActivity"> 


<EditText 
android:id="@+id/editText" 
android: layout_width="O0dp" 
android: layout_height="wrap_content" 
android: layout_marginTop="16dp" 
android:ems="10" 
android: hint="@string/edit_message" 
android: inputType="textPersonName" 
app: layout_constraintLeft_toLeftOf="parent" 
app: layout_constraintTop_toTopOf="parent" 
app: layout_constraintRight_toLeftOf="@+id/button" 
android: layout_marginLeft="16dp" /> 


<Button 

android: id="@+id/button" 

android: layout_width="wrap_content" 

android: layout_height="wrap_content" 

android: text="@string/button_send" 

app: layout_constraintBaseline_toBaselineOf="@+id/editText" 

app: layout_constraintLeft_toRightOf="@+id/editText" 

app: layout_constraintRight_toRightOf="parent" 

android: layout_marginLeft="16dp" 

android: layout_marginRight="16dp" /> 
«/android.support.constraint.ConstraintLayout» 


想 要 了 解 更 多 关于 chain 的 信息 或 者 更 多 关于 ConstraintLayout 的 使 用 方法 ， 可 以 参考 Build 
a Responsive UI with ConstraintLayout ° 


运行 我 们 的 app 


如 果 在 上 一 课 中 已 经 将 app 安装 在 设备 上 了 ， 只 要 点 击 工具 栏 中 Apply Changes h 按钮 
就 可 以 将 最 新 的 布局 更 新 到 手机 上 。 或 者 点 击 Run > 按钮 将 app 安装 到 手机 上 并 运行 。 


目前 为 止 ， 当 我 们 点 击 Button 时 仍然 不 会 有 任何 反应 ， 下 一 课 中 我 们 将 完善 app， 点 击 
Button 时 会 启动 另 一 个 Activity。 


下 一 节 : 局 动 另 一 个 Activity 


建立 简单 的 用 户 界 面 
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Ja z A — ^ Activity 


^h 5 :crazypudding - /$ X:http://developer.android.com/training/basics/firstapp/starting- 
activity.html 


在 完成 上 一 课 (建立 简单 的 用 户 界面 ) 后 ， 我 们 已 经 拥有 了 显示 一 个 activity (一 个 界面 ) 的 
app (应 用 ) ， 该 activity 包含 了 一 个 文本 字段 和 一 个 按钮 。 在 这 节 课 中 ， 你 将 添加 一 些 新 的 
代码 到 MyActivity 中 ， 当 用 户 点 击发 送 (Send) 按 钮 时 启动 一 个 新 的 activity。 


注意 : 本 课程 内 容 期 待 的 运行 环境 为 Android Studio 2.3 及 以 上 


*5 5 Send( X iX dz 42 


按 以 下 步骤 在 MainActivity.java 文件 中 新 增 一 个 方法 ， 该 方法 会 在 我 们 点 击 Send 按钮 时 触 
发 : 


1. 打 开 文 件 app/java/com.example.myfirstapp/MainActivity.java ， 在 其 中 添加 一 个 
sendMessage() 方法 存根 (Method Stub) 


public class MainActivity extends AppCompatActivity { 
QOverride 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity main); 


} 


/** 当 用 户 点 击 Send 按钮 时 调用 该 方法 */ 
public void sendMessage(View view) { 
// 此 处 的 代码 会 在 点 击 Send 按钮 时 执行 


} 


这 里 可 能 会 出 现 名 为 "Cannot resolve symbol" 的 报错 ， 在 方法 参数 View 下 面 会 出 现 一 条 红 
色 的 波浪 线 ， 这 是 因为 Android Studio 不 能 解析 view 类 。 将 光标 移动 到 View 上 ， 然 后 按 
下 Alt+ Enter (Mac? A Option + Return) 组 合 键 快速 修复 。 (如 果 出 现 菜单 ， 则 选择 
Import class) 


2. 现 在 回 到 activity main.xml 文件 ， 完 成 对 sendMessage() 方法 的 调用 : 


1. 在 布局 编辑 器 中 选中 Buton 对 象 


2. 在 **Property** 面板 中 找到 *onClick* 属性 ， 在 下 拉 列 表 中 选中 **sendMessage [MainActivity]** 


完成 这 些 操作 后 ， 当 点 击 Send 按钮 时 ， 系 统 会 调用 sendMessage() 方法 。 


为 保证 系统 能 将 sendMessage() 方法 与 android:onclick 成 功 匹 配 ， 这 个 方法 需要 满足 以 下 要 


e 方法 的 访问 修饰 符 为 public 
e 无 返回 值 
只 有 一 个 View 类 型 的 参数 (代表 被 点 击 的 View 对 象 ) 


接 下 来 ， 你 可 以 在 这 个 方法 中 编写 读 取 文本 内 容 ， 并 将 该 内 容 传 到 另 一 个 Activity 的 代码 。 


构建 一 个 Intent 


Intent 是 一 个 可 以 为 不 同 组 件 在 运行 时 提供 链接 的 对 象 ， 例 如 为 两 个 Activity 提供 链接 。 
Intent 代表 一 个 app“ 想 要 做 某 事 的 意向 "， 你 可 以 使 用 它 来 完成 各 种 各 样 的 任务 ， 不 过 在 本 节 
课程 中 ， 我 们 只 使 用 intent 来 启动 另 一 个 Activity。 


在 MainActivity.java 文件 中 ， 添 加 一 个 EXTRA MESSAGE 常量 并 完善 sendMesage() 7 
法 中 的 代码 ， 如 下 所 示 : 


public class MainActivity extends AppCompatActivity { 
public static final String EXTRA MESSAGE = "com.example.myfirstapp.MESSAGE"; 
@Override 
protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
setContentView(R.layout.activity main); 


/** ZH P Aa Send 按钮 时 调用 该 方法 */ 

public void sendMessage(View view) { 
Intent intent - new Intent(this, DisplayMessageActivity.class); 
EditText editText - (EditText) findViewById(R.id.editText); 
String message - editText.getText().toString(); 
intent.putExtra(EXTRA MESSAGE, message); 
startActivity(intent); 


Android Studio 可 能 会 再 次 出 现 "Cannot resolve symbol" 的 错误 ， 同 样 使 用 Alt + Enter 
(Mac? X Option + Return) 组 合 键 快 速 导 入 类 ， 完 成 后 该 类 的 导入 项 如 下 所 示 : 


import android.content.Intent; 

import android.support.v7.app.AppCompatActivity; 
import android.os.Bundle; 

import android.view.View; 

import android.widget.EditText; 


不 过 对 DisplayMessageActivity 的 引用 仍然 会 报错 ， 因 为 这 个 类 还 不 存在 ; 暂时 先 忽 略 这 个 
错误 ， 我 们 很 快 就 会 解决 这 个 问题 。 


以 下 是 sendMessage() 方法 中 要 注意 的 几 个 地 方 : 

1. Intent 构造 方法 中 有 两 个 参数 : 

2. 第 一 个 参数 是 Context (之 所 以 用 this 是 因为 Activity 类 是 context 的 子 类 ) 

3， 接 受 系 统 发 送 Intent 的 应 用 组 件 对 应 的 Class (在 这 个 案例 中 ， 指 将 要 被 启动 的 activity ) 


4. putExtra() 方法 将 从 EditText 中 取 到 的 值 附加 到 Intent 上 。 Intent 可 以 以 键 - 值 对 的 方式 
携带 数据 ， 这 些 数据 称 为 extras。 此 处 的 键 是 一 个 public 修饰 的 常量 一 一 
EXTRA MESSAGE ， 因 为 在 另 一 个 Activity 中 ， 我 们 需要 以 这 个 键 来 获取 它 对 应 的 值 。 
以 应 用 包 名 为 前 级 来 定义 intent extras 的 键 是 一 个 很 好 的 习惯 ， 这 使 得 app 在 与 其 他 
app 交互 的 过 程 中 能 保证 这 个 键 的 唯一 性 。 


5. startActivity() 方法 启动 了 Intent 定义 的 DisplayMessageActivity 的 实例 。 现 在 我 们 需要 


新 建 一 个 DisplayMessageActivity 类 。 


创建 第 二 个 Activity 


1.4 Project 面板 中 ， 右 击 app 文件 来， 依次 选择 New > Activity > Empty Activity ° 


2. 在 弹出 的 Configure Activity 面板 中 ， 将 Activity Name 的 值 修改 为 
"DispalyMessageActivity" ， 其 他 属性 保持 默认 然后 点 击 finsh 。 


在 这 个 过 程 中 ， Android Studio 自动 完成 了 一 下 三 件 事 : 


e 创 建 了 一 个 名 为 DisplayMessageActivity.java 的 文件 。 

e 创 建 一 个 相应 的 布局 文件 activity display message.xml ° 

e 在 AndroidManifest.xml 文件 中 为 该 文件 添加 了 对 应 的 \ 标 签 (没有 这 个 标签 将 不 能 启动 
相应 的 Activity) 。 


如 果 现 在 运行 app 并 点 击 第 一 个 Activity 中 的 Send 按钮 ， app 4 会 跳 转 到 第 二 个 Activity (也 
就 是 刚 新 建 的 DisplayMessageActivity) 但 是 显示 一 片 空 白 。 这 是 因为 新 建 的 Activity 默认 使 
用 模板 提供 的 空白 布局 页 (activity_display_message) ° 


启动 其 他 的 Activity 


新 增 一 个 TextView 
由 于 新 建 的 Activity 引用 了 一 个 空白 的 布局 页 ， 所 以 我 们 现在 在 这 个 布局 页 中 添加 一 个 
TextView 用 来 显示 信息 。 


1. 打 开 文 件 app/res/layout/activity display message.xml ° 


—- 
2. 打 开 自 动 连接 功能 ， 点 击 工具 栏 中 的 Turn On Autoconnect A 按钮 。 


3. 在 Pallete 面板 中 选中 TextView ， 将 它 拖 到 布局 中 靠近 父 布局 顶部 并 且 大 约 水 平 居中 的 位 
置 ， 当 在 布局 中 央 会 出 现 一 条 虚线 时 放下 。 这 步 操 作 后 ，ConstraintLayout 的 自动 连接 功能 
(Autoconnect) 为 TextView 新 增 了 相应 的 约束 使 其 水 平 居 中 。 


4. 为 TextView 的 顶部 和 父 布 局 顶部 新 增 一 个 约束 ， 这 时 效果 图 如 图 1。 
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图 1. TextView 在 布局 中 水 平 居中 


当然 ， 也 可 以 为 TextView 做 一 些 样式 调整 。 在 Properties 面板 中 展开 TextAppearance % 


项 改变 其 中 一 些 属 性 的 值 ， 比 如 textSize 和 textColor » 


EIL 
显示 消 息 
现在 我 们 来 修改 第 二 个 Activity， 修 改 完 成 便 可 以 接收 第 一 个 Activity 发 来 的 消息 。 


1.4& DisplayMessageActivity.java 文件 中 ， 往 oncreate() 方法 添加 一 下 代码 : 
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@Override 

protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
setContentView(R.layout.activity display message); 


// 获取 启动 此 Activity 的 Intent 并 从 中 取得 附带 的 消息 
Intent intent = getIntent(); 
String message - intent.getStringExtra(MainActivity.EXTRA MESSAGE); 


// 获取 布局 中 TextView 并 为 其 设置 文本 信息 
TextView textView = (TextView) findViewById(R.id.textView); 
textView.setText(message); 


2. 利 用 组 合 键 Alt + Enter (Mac 中 为 Option + Return) 导入 需要 的 类 。 完 成 后 该 类 的 导入 项 
如 下 : 


import android.content.Intent; 

import android.support.v7.app.AppCompatActivity; 
import android.os.Bundle; 

import android.view.ViewGroup; 

import android.widget.TextView; 


添加 向 上 导航 (Up Navigation) 


我 们 应 该 为 app 中 所 有 不 是 主要 入 口 的 页 面 添加 导航 ， 这 样 一 来 用 户 便 可 以 通过 app bar 中 
的 Up 按钮 返回 到 当前 页 面 的 逻辑 父 页 面 


我 们 所 需要 做 的 就 是 在 [AndroidManifest.xml] 文件 中 为 声明 哪 一 个 Activity 是 它 的 逻辑 父 项 。 
打开 清单 文件 ，app/Manifest/AndroidManifest.xml ,在 名 为 DisplayMessageActivity 的 标签 
中 新 增 一 下 内 容 : 


«activity android:name=".DisplayMessageActivity" 
android:parentActivityName-".MainActivity" > 
«!-- meta-data 标签 是 为 了 兼容 API 15 及 以 下 的 设备 --> 
<meta-data 
android:name-"android.support.PARENT ACTIVITY" 
android: value=".MainActivity" /> 
</activity> 


现在 Android 系统 已 经 自动 在 DisplayMessageActivity 的 app bar 中 添加 了 Up 按钮 。 


` 


运行 app 


现在 点 击 工 具 栏 中 的 Apply Changes k 按钮 再 次 运行 App。 运行 成 功 之 后 ， 试 着 在 
EditText 中 输入 文字 信息 如 : "Hello world!" 并 点 击 Send 按钮 ， 你 会 看 到 信息 已 经 显示 在 第 二 
个 Activity 中 了 。 如 图 : 


Pd 7:00 9 "4 & 7:00 


My First App 《和  MyFirst App 





Hello world! SEND Hello world! 


到 此 为 止 ， 已 经 创建 好 我 们 的 第 一 个 Android 应 用 了 ! 想 要 继续 学 习 Android 应 用 开发 的 基础 
知识 ， 通 过 下 面 的 链接 进入 到 下 一 课 吧 。 


“<2 Action Bar 


编写 :Vincent 4J - Æ X:http://developer.android.com/training/basics/actionbar/index.html 


Action Bar 是 我 们 可 以 为 activity 实 现 的 最 重要 的 设计 元 素 之 一 。 其 提供 了 多 种 Ul? TY 
让 我 们 的 app 与 其 他 Android app 保持 较 高 的 一 致 性 ， 从 而 为 用 户 所 熟悉 。 核 心 的 功能 包 
括 : 


e 一 个 专门 的 空间 用 来 显示 你 的 app 的 标识 ， 以 及 指出 目前 所 处 在 app 的 哪个 页 面 。 
e 以 一 种 可 预见 的 方式 访问 重要 的 操作 (比如 搜索 ) © 
e 支持 导航 和 视图 切换 (通过 Tabs 和 下 拉 列 表 ) 


WY Action Bar Q, 


AA action bar 的 基本 知识 提供 了 一 个 快速 指南 。 关 于 action bar 的 更 多 特性 ， 请 查看 
Action Bar 指南 。 


Lessons 


e 建立 ActionBar 


学 习 如 何 为 activity 添加 一 个 基本 的 action bar， 是 仅仅 支持 Android 3.0 及 以 上 的 版 本 ， 
还 是 同时 也 支持 至 Android 2.1 的 版 本 (通过 使 用 Andriod Support Library) ° 


e 添加 Action 按 包 

学 习 如 何在 action bar 中 添加 和 响应 用 户 操 作 。 
e ActionBar 的 风格 化 

学 习 如 何 自 定义 action bar 的 外 观 。 


ActionBar E 5 & 7» 


学 习 如 何在 布局 上 面倒 加 action bar， 人 允许 action bar 隐藏 时 无 缝 过渡 。 


建立 ActionBar 


编写 :Vincent 4J - /$ X<:http://developer.android.com/training/basics/actionbar/setting- 


up.html 


Action bar 最 基本 的 形式 ， 就 是 为 Activity 显示 标题 ， 并 且 在 标题 左边 显示 一 个 app icon ° FP 
使 在 这 样 简单 的 形式 下 ，action bar 对 于 所 有 的 activity 来 说 是 十 分 有 用 的 。 它 告知 用 户 他 们 
当前 所 处 的 位 置 ， 并 为 你 的 app 维护 了 持续 的 同一 标识 。 


| Action Bar 


图 1. 一 个 有 app icon 和 Activity 标题 的 action bar 


设置 一 个 基本 的 action bar， 需 要 app 使 用 一 个 activity 主题 ， 该 主题 必须 是 action bar 可 用 
的 。 如 何 声明 这 样 的 主题 取决 于 我 们 app 支持 的 Android 最 低 版 本 。 本 课程 根据 我 们 app X 
持 的 Android 最 低 版 本 分 为 两 部 分 。 


仅 支 持 Android 3.0 及 以 上 版 本 


从 Android 3.0(API lever 11) 开始 ， 所 有 使 用 Theme.Holo 主题 (或 者 它 的 子 类 ) 的 Activity 
都 包含 了 action bar > 4 targetSdkVersion 或 minSdkVersion 属性 被 设置 成 “11” 或 更 大 时 ， 


它 是 默认 主题 。 


所 以 ， 要 为 activity 添加 action bar， 只 需 简 单 地 设置 属性 为 11 或 者 更 大 。 例 如 : 


«manifest ... » 
«uses-sdk android:minSdkVersion="11" ... /> 
«/manifest» 


注意 : 如 果 创 建 了 一 个 自 定 义 主题 ， 需 确保 这 个 主题 使 用 一 个 Theme.Holo 的 主题 作为 父 
类 。 详 情 见 Action bar 的 风格 化 


到 此 ， 我 们 的 app 使 用 了 rheme.Holo 主题 ， 并 且 所 有 的 activity 都 显示 action bar ° 


支持 Android 2.1 及 以 上 版 本 


4 app 运行 在 Andriod 3.0 以 下 版 本 (不 低 于 Android 2.1) 时 ， 如 果 要 添加 action bar， 需 
要 加 载 Android Support 库 。 


开始 之 前 ， 通 过 阅读 Support Library Setup 文 档 来 建立 v7 appcompat library (下 载 完 library 
包 之 后 ， 按 照 Adding libraries with resources 的 指引 进行 操作 ) 。 


在 Support Library 集 成 到 你 的 app 工程 中 之 后 : 


1、 更 新 activity， 以 便于 它 继承 于 ActionBarActivity。 例 如 : 


public class MainActivity extends ActionBarActivity { ... ) 


2^ # mainfest 文件 中 ， 更 新 <application> 标签 或 者 单一 的 <activity> 标签 来 使 用 一 个 
Theme.AppCompat 主题 。 例 如 : 


«activity android:theme-"Qstyle/Theme.AppCompat.Light" ... > 


注意 : 如 果 创 建 一 个 自 定义 主题 ， 需 确 保 其 使 用 一 个 Theme .AppCompat 主题 作为 父 类 。 详 
情 见 Action bar 风格 化 


现在 ， 当 app 运行 在 Android 2.1(API level 7) 或 者 以 上 时 ，activity 将 包含 action bar。 


切记 ， 在 manifest 中 正确 地 设置 app 支持 的 APl level : 


<manifest e 
«uses-sdk android:minSdkVersion-"7" android: targetSdkVersion="18" /> 


«/manifest» 


Aste Actiondz 42 


编写 :Vincent 4J - Æ X:http://developer.android.com/training/basics/actionbar/adding- 
buttons.html 


Action bar 允许 我 们 为 当前 环境 下 最 重要 的 操作 添加 按钮 。 那 些 直 接 出 现在 action bar 中 的 
icon 和 /或 文本 被 称 作 action buttons( 操 作 按 钮 )。 安 排 不 下 的 或 不 足够 重要 的 操作 被 隐藏 在 
action overflow (超出 空间 的 action， 译 者 注 ) 中 。 


i}! Action Bar Q, 


图 1. 一 个 有 search 操 作 按 钮 和 action overflow 的 action bar > # action overflow 里 能 展现 额 
外 的 操作 。 


在 XML 中 指定 操作 


所 有 的 操作 按钮 和 action overflow 中 其 他 可 用 的 条 目 都 被 定义 在 menu 资 源 的 XML 文件 中 。 
通过 在 项 目的 res/menu 目录 中 新 增 一 个 XML 文件 来 为 action bar 添加 操作 。 


为 想 要 添加 到 action bar 中 的 每 个 条 目 添 加 一 个 <item> 元 素 。 例 如 : 


res/menu/main activity actions.xml 


<!-- 搜索 ， 应 该 作为 动作 按钮 展示 --> 

«item android:id="@+id/action_ search" 
android:icon-z"Qdrawable/ic action search" 
android:title-"Qstring/action search" 
android:showAsAction-"ifRoom" /» 

<!-- Re, JEGbdQ XE Pea --> 

<item android:id="@tid/action_settings" 
android:title-"Qstring/action settings" 
android:showAsAction-"never" /» 

«/menu» 


bit 4X8 P5 8H > 3$ action bar 有 可 用 空间 时 ， 搜 索 操 作 将 作为 一 个 操作 按钮 来 显示 ， 但 设置 
操作 将 一 直 只 在 action overflow 中 显示 。 (默认 情况 下 ， 所 有 的 操作 都 显示 在 action 
overflow 中 ， 但 为 每 一 个 操作 指明 设计 意图 是 很 好 的 做 法 。) 


icon 属性 要 求 每 张 图 片 提 供 一 个 resource ID ° Æ Qdrawable/ 之 后 的 名 字 必 须 是 存储 在 项 
目 目 录 res/drawable/ 下 位 图 图 片 的 文件 名 。 例 如 : ic action search.png 对 应 

"(QQdrawable/ic action search" ° 4] 4€ 36 > title ipei 通过 XML 文件 定义 在 项 目 目录 
res/values/ 中 的 一 个 string 资源 ， 详 情 请 参见 创建 一 个 简单 的 Ul 。 


注意 : 当 创建 icon 和 其 他 bitmap 图 片 时 ， 要 为 不 同 屏 医 密度 下 的 显示 效果 提供 多 个 优 
化 的 版 本 ， 这 一 点 很 重要 。 在 支持 不 同 屏幕 课程 中 将 会 更 详细 地 讨论 。 


如 果 为 了 兼容 Android 2.1 的 版 本 使 用 了 Support 库 ， 在 android 命名 空间 下 
showAsAction 属性 是 不 可 用 的 。Support 库 会 提供 替代 它 的 属性 ， 我 们 必须 声明 自己 的 XML 
命名 空间 ， 并 且 使 用 该 命名 空间 作为 属性 前 级 。 (一 个 自 定 义 XML 命名 空间 需要 以 我 们 的 
app 名 称 为 基础 ， 但 是 可 以 取 任 何 想 要 的 名 称 ， 它 的 作用 域 仅 仅 在 我 们 声明 的 文件 之 内 。) 
例如 : 


res/menu/main activity actions.xml 


«menu xmlns:android="http://schemas.android.com/apk/res/android" 
xmlns:yourapp="http://schemas.android.com/apk/res-auto" > 


<!-- Ax, 应 该 展示 为 天 动作 按 和 HB --> 





«item android:id-z"Q-id/action search" 
android:icon-z"Qdrawable/ic action search" 
android: title="@string/action_search" 
yourapp:showAsAction-"ifRoom" /> 


</menu> 


A Action Bar 添加 操作 


A action bar 布局 菜单 条 目 ， 就 要 在 activity ? 实现 onCreateOptionsMenu() 回调 方法 来 
inflate 菜单 资源 从 而 获取 Menu 对 象 。 例 如 


@Override 

public boolean onCreateOptionsMenu(Menu menu) { 
// 为 ActionBar 扩 展 菜单 项 
MenuInflater inflater = getMenuInflater(); 
inflater.inflate(R.menu.main activity actions, menu); 
return super.onCreateOptionsMenu(menu); 


为 操作 按钮 添加 响应 事件 


当 用 户 按 下 某 一 个 操作 按钮 或 者 action overflow 中 的 其 他 条 目 ， 系 统 将 调用 activity 中 
onOptionsltemSelected() 的 回调 方法 。 在 该 方法 的 实现 里 面 调用 Menultem 的 getltemld() 来 判 
断 哪个 条 目 被 按 下 - 返回 的 ID 会 匹配 我 们 声明 对 应 的 <item> JG T android:id 属性 的 
值 。 


@Override 
public boolean onOptionsItemSelected(MenuItem item) { 
// 处 理 动作 按钮 的 点 击 事件 
switch (item.getItemId()) { 
case R.id.action search: 
openSearch(); 
return true; 
case R.id.action_settings: 
openSettings(); 
return true; 
default: 
return super.onOptionsItemSelected(item); 


为 下 级 Activity 添加 向 上 按钮 


在 不 是 程序 入 口 的 其 他 所 有 屏 中 (activity 不 位 于 主屏 时 ) ， 需 要 在 action bar 中 为 用 户 提供 
一 个 导航 到 逻辑 父 屏 的 up button( 向 上 按钮 ) 。 


ee 


图 2. Gmail 中 的 up button 。 


当 运 行 在 Android 4.1(API level 16) 或 更 高 版 本 ， 或 者 使 用 Support 库 中 的 ActionBarActivity 
时 ， 实 现 向 上 导航 需要 在 manifest 文件 中 声明 父 activity ， 同 时 在 action bar 中 设置 向 上 按钮 
可 用 。 


如 何在 manifest 中 声明 一 个 activity 的 父 类 ， 例 如 : 


<application = 
<!-- £€ main/home 活动 (没有 上 级 活动 ) --» 
«activity 
android:name="com.example.myfirstapp.MainActivity" ...> 
</activity> 


cl 了 活动 的 一 个 了 活动 > 
<activity 
android:name="com.example.myfirstapp.DisplayMessageActivity" 
android:label-"Qstring/title activity display message" 
android:parentActivityName-"com.example.myfirstapp.MainActivity" » 
<!-- meta-data 用 于 支持 support 4.0 以 及 以 下 来 指明 上 级 活动 --> 
<meta-data 
android:name-"android.support.PARENT ACTIVITY" 
android:value-"com.example.myfirstapp.MainActivity" /> 
«/activity» 
</application> 


然后 ， 通 过 调用 setDisplayHomeAsUpEnabled() X4& app icon 设置 成 可 用 的 向 上 按钮 : 


@Override 

public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState) ; 
setContentView(R.layout.activity displaymessage); 


getSupportActionBar().setDisplayHomeAsUpEnabled(true); 
// 如 果 你 的 minSsdkVersion 属 性 是 11 或 更 高 ， 应 该 这 么 用 : 
// getActionBar().setDisplayHomeAsUpEnabled(true); 


由 于 系统 已 经 知道 MainActivity Æ DisplayMessageActivity 的 父 activity， 当 用 户 按 下 向 上 


按钮 时 ， 系 统 会 导航 到 恰当 的 父 activity - 你 不 需要 去 处 理 向 上 按钮 的 事件 。 


更 多 关于 向 上 导航 的 信息 ， 请 见 提供 向 上 导航 。 
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自 定 义 ActionBar 的 风格 


编写 :Vincent 4J - 原 


x-:http://developer.android.com/training/basics/actionbar/styling.html 


Action bar 为 用 户 提供 一 种 熟悉 可 预测 的 方式 来 展示 操作 和 导航 ， 但 是 这 并 不 意味 着 我 们 的 
app 要 看 起 来 和 其 他 app 一 样 。 如 果 想 将 action bar 的 风格 设计 的 合乎 我 们 产品 的 定位 ， 只 
需 简单 地 使 用 Android 的 样式 和 主题 资源 。 


Android 包括 一 少 部 分 内 置 的 activity 主题 ， 这 些 主 题 中 包含 “dark” X "light" 的 action bar 样 
式 。 我 们 也 可 以 扩展 这 些 主题 ， 以 便于 更 好 的 为 action bar 自 定义 外 观 。 
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使 用 一 个 Android 主题 


Android 包含 两 个 基本 的 activity 主题 ， 这 两 个 主题 决定 了 action bar 的 颜色 : 


e Theme.Holo > —* “dark” 的 主题 
e Theme.Holo.Light > — ^ "light" 的 主题 


图 | Action Bar 


Theme.Holo 





(tJ! Action Bar or 


Theme.Holo.Light 


vcuonbpar: 


这 些 主题 即 可 以 被 应 用 到 app 全 局 ， 也 可 以 通过 在 manifest 文件 中 设置 <application> 元 素 
或 <activity> 元 素 的 android:theme 属性 ， 对 单一 的 activity 进行 设置 。 


例如 : 


«application android:theme-"Qandroid:style/Theme.Holo.Light" ... /» 


可 以 通过 声明 activity 的 主题 为 Theme.Holo.Light.DarkActionBar 来 达到 如 下 效果 : action 
bar 为 dark， 其 他 部 分 为 light ° 


$! Action Bar 





Theme.Holo.Light.DarkActionBar 


当 使 用 Support 库 时 ， 必 须 使 用 Theme.AppCompat 主题 替代 : 


e Theme.AppCompat > 一 个 “dark” 的 主题 
e Theme.AppCompat.Light， 一 个 light 的 主题 
e Theme.AppCompat.Light.DarkActionBar， 一 个 带 有 “dark” action bar 的 “light 主题 


一 定 要 确保 我 们 使 用 的 action bar icon 的 颜色 与 action bar 本 身 的 颜色 有 差异 。Action Bar 
Icon Pack 为 Holo "dark" fe"light" 5 action bar 提供 了 标准 的 action icon ° 


自 定 义 背 景 


为 改变 action bar 的 背景 ， 可 以 通过 为 activity 创建 一 个 自 定义 主题 ， 并 重 写 actionBarStyle 
属性 来 实现 。actionBarStyle 属性 指向 另 一 个 样式 ; 在 该 样式 里 ， 通 过 指定 一 个 drawable 资 
源 来 重 写 background 属性 。 


e Action Bar 





Custom background theme 


如 果 我 们 的 app 使 用 了 navigation tabs 或 split action bar ， 也 可 以 通过 分 别 设置 
backgroundStacked 和 backgroundSplit 属性 来 为 这 些 条 指定 背景 。 


Note: 为 自 定义 主题 和 样式 声明 一 个 合适 的 父 主题 ， 这 点 很 重要 。 如 果 没 有 父 样 式 ， 
action bar 将 会 失去 很 多 默认 的 样式 属性 ， 除 非 我 们 自己 显 式 的 对 他 们 进行 声明 o 


仅 支 持 Android 3.0 和 更 高 


当 仅 支持 Android 3.0 和 更 高 版 本 时 ， 可 以 通过 如 下 方式 定义 action bar 的 背景 : 


res/values/themes.xml 


<?xml version="1.0" encoding="utf-8"?> 
<resources> 
<!-- 应 用 于 程序 或 者 活动 的 主题 - -> 
«style name="CustomActionBarTheme" 
parent="@android:style/Theme.Holo.Light .DarkActionBar"> 
<item name="android:actionBarStyle">@style/MyActionBar</item> 
</style> 


<!-- ActionBar 样式 --> 
<style name="MyActionBar" 
parent="@android:style/Widget.Holo.Light.ActionBar .Solid.Inverse"> 
<item name="android:background">@drawable/actionbar_background</item> 


</style> 
</resources> 


然后 ， 将 主题 应 用 到 app 全 局 或 单个 的 activity 之 中 : 


«application android:theme-"Qstyle/CustomActionBarTheme" ... /> 


支持 Android 2.1 和 更 高 


当 使 用 Support 库 时 ， 上 面 同样 的 主题 必须 被 蔡 代 成 如 下 : 


res/values/themes.xml 


<?xml version="1.0" encoding="utf-8"?> 
<resources> 
<!-- 应 用 于 程序 或 者 活动 的 主题 --> 
<style name="CustomActionBarTheme" 
parent-z"Qstyle/Theme.AppCompat.Light.DarkActionBar"» 
«item name="android:actionBarStyle">@style/MyActionBar</item> 


<!-- 支持 库 兼 容 --> 
«item name="actionBarStyle">@style/MyActionBar</item> 
«/style» 
«!-- ActionBar 样式 --> 


«style name="MyActionBar" 
parent="@style/widget .AppCompat.Light.ActionBar .Solid.Inverse"> 
<item name="android:background">@drawable/actionbar_background</item> 


<!-- XBRRE --> 

<item name="background">@drawable/actionbar_background</item> 
</style> 
</resources> 


然后 ， 将 主题 应 用 到 app 全 局 或 单个 的 activity 之 中 : 


«application android:theme-"Qstyle/CustomActionBarTheme" ... /> 


Ae 3L SC AK ZR E 
修改 action bar 中 的 文本 颜色 ， 需 要 分 别 设置 每 个 元 素 的 属性 : 


e Action bar 的 标题 : 创建 一 种 自 定义 样式 ， 并 指定 textcolor 属性 ; 同时， 在 自 定义 的 
actionBarStyle 中 为 titleTextStyle 属性 指定 为 刚才 的 自 定义 样式 。 


注意 : 被 应 用 到 titleTextStyle 的 自 定义 样式 应 该 使 用 
TextAppearance.Holo.Widget.ActionBar.Title 作为 父 样式 。 


e Action bar tabs : 在 activity 主题 中 重 写 actionBarTabTextStyle 
e Action #42 : 在 activity 主题 中 重 写 actionMenuTextColor 


仅 支 持 Android 3.0 和 更 高 


当 仅 支持 Android 3.0 和 更 高 时 ， 样 式 XML 文件 应 该 是 这 样 的 : 


res/values/themes.xml 
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<?xml version="1.0" encoding="utf-8"?> 
<resources> 
<!-- 应 用 于 程序 或 者 活动 的 主题 --> 
«style name="CustomActionBarTheme" 
parent="@style/Theme.Holo"> 
<item name="android:actionBarStyle">@style/MyActionBar</item> 
<item name="android:actionBarTabTextStyle">@style/MyActionBarTabText</item> 
«item name="android:actionMenuTextColor">@color/actionbar_text</item> 
</style> 


<!-- ActionBar 样式 --> 
<style name="MyActionBar" 
parent="@style/Widget .Holo.ActionBar'"> 
«item name="android:titleTextStyle">@style/MyActionBarTitleText</item> 
</style> 


<!-- ActionBar 标题 文本 --> 
<style name="MyActionBarTitleText" 
parent="@style/TextAppearance.Holo.Widget .ActionBar .Title"> 
<item name="android:textColor">@color/actionbar_text</item> 
</style> 


<!-- ActionBar Tabis € x ARRA --» 
«style name="MyActionBarTabText" 
parent="@style/Widget.Holo.ActionBar .TabText"> 
<item name="android:textColor">@color/actionbar_text</item> 
</style> 
</resources> 


支持 Android 2.1 和 更 高 


448 Support 库 时 ， 样 式 XML 文件 应 该 是 这 样 的 : 


res/values/themes.xml 


C1 


NO 





<?xml version="1.0" encoding="utf-8"?> 
<resources> 
<!-- 应 用 于 程序 或 者 活动 的 主题 --> 
«style name="CustomActionBarTheme" 
parent="@style/Theme.AppCompat"> 
<item name="android:actionBarStyle">@style/MyActionBar</item> 
<item name="android:actionBarTabTextStyle">@style/MyActionBarTabText</item> 
«item name="android:actionMenuTextColor">@color/actionbar_text</item> 


<!-- 支持 库 兼 容 --> 

«item name="actionBarStyle">@style/MyActionBar</item> 

<item name="actionBarTabTextStyle">@style/MyActionBarTabText</item> 

«item name="actionMenuTextColor">@color/actionbar_text</item> 
</style> 


<!-- ActionBar 样式 --> 
<style name="MyActionBar" 
parent="@style/Widget .AppCompat .ActionBar'"> 
<item name="android:titleTextStyle">@style/MyActionBarTitleText</item> 


<!-- XRRE --> 
<item name="titleTextStyle">@style/MyActionBarTitleText</item> 

</style> 

<!-- ActionBar 标题 文本 --> 


<style name="MyActionBarTitleText" 
parent="@style/TextAppearance.AppCompat .Widget .ActionBar.Title"> 
<item name="android: textColor">@color/actionbar_text</item> 
<!-- 文本 颜色 属性 textColLor 是 可 以 配合 支持 库 向 后 兼容 的 --> 
</style> 


<!-- ActionBar Tab 标 签 文本 样式 --> 
«style name="MyActionBarTabText" 
parent="@style/Widget .AppCompat .ActionBar .TabText"> 
<item name="android: textColor">@color/actionbar_text</item> 
<!-- 文本 颜色 属性 textColor 是 可 以 配合 支持 库 向 后 兼容 的 --> 
</style> 
</resources> 


É X 3. Tab Indicator 


为 activity 创建 一 个 自 定 义 主题 ， 通 过 重 写 actionBarTabStyle 属性 来 改变 navigation tabs 使 
用 的 指示 器 。actionBarTabStyle 属性 指向 另 一 个 样式 资源 ; 在 该 样式 资源 里 ， 通 过 指定 一 个 
state-list drawable 来 重 写 background 属性 。 


自 定 义 ActionBar 的 风格 


è Action Bar 





注意 : 一 个 state-list drawable 是 重要 的 ， 它 可 以 通过 不 同 的 背景 来 指出 当前 选择 的 tab 
与 其 他 tab 的 区 别 。 更 多 关于 如 何 创建 一 个 drawable 资源 来 处 理 多 个 按钮 状态 ， 请 阅读 
State List 文档 。 
例如 ， 这 是 一 个 状态 列表 drawable， 为 一 个 action bartab 的 多 种 不 同 状态 分 别 指 定 背 景 图 
片 : 


res/drawable/actionbar tab indicator.xml 
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自 定 义 ActionBar 的 风格 


<?xml version="1.0" encoding="utf-8"?> 
«selector xmlns:android-"http://schemas.android.com/apk/res/android"» 


«1-- 按钮 没有 按 下 的 状态 --> 


<!-- 没有 焦点 的 状态 --> 


«item android: 
android: 
android: 

«item android: 
android: 
android: 


state focused-"false" android:state selected-"false" 
state pressed-'"false" 
drawable="@drawable/tab_unselected" /> 

state focused-z"false" android:state_selected="true" 
state pressed-"false" 

drawable-"Qdrawable/tab selected" /> 


«1-- 有 焦点 的 状态 (例如 D-Pad 控 制 或 者 鼠标 经 过 ) --» 


«item android: 
android: 
android: 

«item android: 
android: 
android: 


state focusedz"true" android:state_selected="false" 
state_pressed="false" 
drawable="@drawable/tab_unselected_focused" /> 
state_focused="true" android:state_selected="true" 
state_pressed="false" 
drawable="@drawable/tab_selected_focused" /> 


<1-- ”按钮 按 下 的 状态 D --> 


<!-- 没有 焦点 的 状态 --> 


«item android: 
android: 
android: 

«item android: 


state focused-"false" android:state selected-"false" 
state pressed-"true" 
drawable-"Qdrawable/tab unselected pressed" /» 
state focusedz"false" android:state selected-'true" 


android:state pressed-"true" 
android:drawable-"Qdrawable/tab selected pressed" /> 


<1-- 有 焦点 的 状态 (例如 D-Pad 控 制 或 者 鼠标 经 过 ) - -> 


«item android: 
android: 
:drawable-"Qdrawable/tab unselected pressed" /> 


android 


«item android: 
android: 


android 
</selector> 


state_focused="true" android:state_selected="false" 
state_pressed="true" 


state_focused="true" android:state_selected="true" 
state_pressed="true" 


:drawable="@drawable/tab_selected_pressed" /> 


42 € 4& Android 3.0 和 更 高 


当 仅 支持 Android 3.0 和 更 高 时 ， 样 式 XML 文件 应 该 是 这 样 的 : 


res/values/themes.xml 
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自 定 义 ActionBar 的 风格 


<?xml version="1.0" encoding="utf-8"?> 
«resources» 
<!-- 应 用 于 程序 或 活动 的 主题 --> 
«style name="CustomActionBarTheme" 


parent="@style/Theme.Holo"> 
<item name="android:actionBarTabStyle">@style/MyActionBarTabs</item> 


</style> 


<!-- ActionBar tabs 标签 样式 --> 


<style name="MyActionBarTabs" 
parent="@style/Widget .Holo.ActionBar . TabView"> 


<!-- 标签 指示 器 --> 
«item name="android:background">@drawable/actionbar_tab_indicator</item> 


</style> 
</resources> 


支持 Android 2.1 和 更 高 
当 使 用 Support EH. > 4E X, XML 文件 应 该 是 这 样 的 : 
res/values/themes.xml 


<?xml version="1.0" encoding-'utf-8"?» 


<resources> 
<1-- 应 用 于 程序 或 活动 的 主题 --> 
«style name="CustomActionBarTheme" 


parent="@style/Theme.AppCompat"> 
<item name="android:actionBarTabStyle">@style/MyActionBarTabs</item> 


<!-- 支持 库 兼 容 --> 
«item name="actionBarTabStyle">@style/MyActionBarTabs</item> 
«/style» 
<!-- ActionBar tabs ##X --> 


<style name="MyActionBarTabs" 
parent="@style/Widget .AppCompat .ActionBar . TabView"> 


<!-- 标签 指示 器 --> 
«item name="android:background">@drawable/actionbar_tab_indicator</item> 


<!-- 支持 库 兼 容 --> 
«item name="background">@drawable/actionbar_tab_indicator</item> 


</style> 
</resources> 


关于 action bar 的 更 多 样式 属性 ， 请 查看 Action Bar 指南 


e 
e 学 习 更 多 样式 的 工作 机 制 ， 请 查看 样式 和 主题 指南 
e 全 面 的 action bar 样式 ， 请 尝试 Android Action Bar 样式 生成 器 


自 定 义 ActionBar 的 风格 
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ActionBar®) & i 4 7» 


编写 :Vincent 4J - 原 
文 :http://developer.android.com/training/basics/actionbar/overlaying.html 


默认 情况 下 ，action bar 显示 在 activity 窗口 的 顶部 ， 会 稍微 地 减少 其 他 布局 的 有 效 空间 。 如 
果 在 用 户 交互 过 程 中 要 隐藏 和 显示 action bar， 可 以 通 ActionBar 中 的 hide()feshow() 
来 实现 。 但 是 ， 这 将 导致 activity 基于 新 尺寸 重新 计算 与 绘制 布局 。 


为 避免 在 action bar 隐藏 和 显示 过 程 中 调整 布局 的 大 小 ， 可 以 为 action bar 启用 三 加 模式 
(overlay mode)。 在 梧 加 模式 下 ， 所 有 可 用 的 空间 都 会 被 用 来 布局 就 像 ActionBar 不 存在 一 
样 ， 并 且 action bar 会 司 加 在 布局 之 上 。 这 样 布局 顶部 就 会 有 点 被 遮挡 ， 但 当 action bar 隐藏 
或 显示 时 ， 系 统 不 再 需要 调整 布局 而 是 无 颖 过渡 。 


Note : RẸ action bar 下 面 的 布局 部 分 可 见 ， 可 以 创建 一 个 背景 部 分 透 
式样 的 action bar， 如 图 1 所 示 。 关 于 如 何 定义 action bar 的 背景 ， 请 2 
ActionBar 的 风格 » 
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图 1. 登 加 模式 下 的 gallery action bar 


Je A & 204% A (Overlay Mode) 


要 为 action bar 启用 受 加 模式 ， 需 要 自 定义 一 个 主题 ， 该 主题 继承 于 已 经 存在 的 action bar = 


题 ， 并 设置 android:windowActionBarOverlay 属性 的 值 为 true 。 


仅 支 持 Android 3.0 和 以 上 


如 果 minSdkVersion 为 11 或 更 高 ， 自 定义 主题 必须 继承 Theme.Holo 主题 (或 者 其 子 主 
XR) 。 例 如 : 


«resources» 
<1-- 为 程序 或 者 活动 应 用 的 主题 样式 --> 
«style name="CustomActionBarTheme" 
parent="@android:style/Theme.Holo"> 
«item name="android:windowActionBarOverlay">true</item> 
</style> 


</resources> 


支持 Android 2.1 和 更 高 


如 果 为 了 兼容 运行 在 Android 3.0 以 下 版 本 的 设备 而 使 用 了 Support 库 ， 自 定义 主题 必须 继承 
Theme.AppCompat 主题 (或 者 其 子 主题 ) 。 例 如 : 


<resources> 
<1-- 为 程序 或 者 活动 应 用 的 主题 样式 --> 
<style name="CustomActionBarTheme" 
parent="@android:style/Theme.AppCompat"> 
«item name="android:windowActionBarOverlay">true</item> 


<!-- 兼容 支持 库 --> 
«item name="windowActionBarOverlay">true</item> 
</style> 


</resources> 
注意 ， 该 主题 包含 两 种 不 同 的 windowactionBaroverlay 式样 定义 : 一 个 带 android: AYA? 


另 一 个 不 带 。 带 前 级 的 适用 于 包含 该 式样 的 Android 系统 版 本 ， 不 带 前 级 的 适用 于 通过 从 
Support 库 中 读 取 式 样 的 旧版 本 。 


和 9 定 布 局 的 顶部 边 距 


当 action bar 启用 受 加 模式 时 ， 它 可 能 会 让 挡住 本 应 保持 可 见 状态 的 布局 。 为 了 确保 这 些 布 
局 始终 位 于 action bar 下 部 ， 可 以 使 用 actionBarSize 属性 来 指定 顶部 margin 或 padding 的 高 
度 来 到 达 。 例 如 : 


<RelativeLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android: layout_width="match_parent" 
android: layout_height="match_parent" 
android: paddingTop="?android:attr/actionBarSize"> 


</RelativeLayout> 


如 果 在 action bar 中 使 用 Support 库 ， 需 要 移 除 android: 前 级 。 例 如 : 


<!|-- #BxGE --> 

<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" 
android: layout_width="match_parent" 
android:layout height-"match parent" 
android: paddingTop="?attr/actionBarSize"> 


</RelativeLayout> 


在 这 种 情况 下 ， 不 带 前 级 的 ?attr/actionBarsize 适用 于 包括 Android 3.0 和 更 高 的 所 有 版 
本 。 


v2 oe — "JL 
兼容 不 同 的 设备 
编写 :Lin-H - 原文 :http://developer.android.com/training/basics/supporting- 
devices/index.html 


全 世界 的 Android 设 备 有 着 各 种 各 样 的 大 小 和 尺寸 。 通 过 各 种 各 样 的 设备 类 型 ， 能 使 我 们 通过 
自己 的 app 接 触 到 广大 的 用 户 群体 。 为 了 能 在 各 种 Android 平 台 上 使 用 ， 我 们 的 app 需 要 兼容 各 
种 不 同 的 设备 类 型 。 某 些 例如 语言 ， 屏 幕 尺 寸 ，Android 的 系统 版 本 等 重要 的 变量 因素 需要 重 
点 考虑 。 


本 课程 会 教 我 们 如 何 使 用 基础 的 平台 功能 ， 利 用 替代 资源 和 其 他 功能 ， 使 app 仅 用 一 个 app 程 
序 包 (APK)， 就 能 向 用 Android 兼 容 设备 的 用 户 提供 最 优 的 用 户 体验 。 


Lessons 


e 适 配 不 同 的 语言 

学 习 如 何 使 用 字符 串 替代 资源 实现 支持 多 国语 言 。 
e 适 配 不 同 的 屏幕 

学 习 如 何 根据 不 同 尺 寸 分 辩 率 的 屏幕 来 优化 用 户 体验 。 
e 适 配 不 同 的 系统 版 本 


学 习 如 何在 使 用 新 的 用 户 编程 接口 (API) 时 向 下 兼容 昌 版 本 Android © 


适 配 不 同 的 语言 


编写 :Lin-H - 原文 :http://developer.android.com/training/basics/supporting- 
devices/languages.html 


把 Ul 中 的 字符 串 存储 在 外 部 文件 ， 通 过 代码 提取 ， 这 是 一 种 很 好 的 做 法 。Android 可 以 通过 工 
程 中 的 资源 目录 轻松 实现 这 一 功能 。 


如 果 使 用 Android SDK Tools( 详 见 创 建 Android 项 目 (Creating an Android Project)) 来 创建 工 
程 ， 则 在 工程 的 根 目 录 会 创建 一 个 res/ 的 目录 ， 目 录 中 包含 所 有 资源 类 型 的 子 目 录 。 其 中 包 
含 工程 的 默认 文件 比如 res/values/strings.xml ， 用 于 保存 字符 串 值 。 


创建 区 域 设 置 目 录 及 字符 串 文 件 


为 支持 多 国语 言 ， 在 res/ 中 创建 一 个 额外 的 values 目录 以 连 字 符 和 ISO 国家 代码 结尾 命 
名 ， 比 如 values-es/ 是 为 语言 代码 为 "es" 的 区 域 设置 的 简单 的 资源 文件 的 目录 。Android 会 在 
运行 时 根据 设备 的 区 域 设置 ， 加 载 相应 的 资源 。 详 见 Providing Alternative Resources ° 


若 决定 支持 茶 种 语言 ， 则 需要 创建 资源 子 目 录 和 字符 串 资源 文件 ， 例 如 : 


MyProject/ 
res/ 

values/ 
strings.xml 

values-es/ 
strings.xml 

values-fr/ 
strings.xml 


添加 不 同 区 域 语言 的 字符 串 值 到 相应 的 文件 。 
Android 系 统 运 行 时 会 根据 用 户 设备 当前 的 区 域 设置 ， 使 用 相应 的 字符 串 资 源 。 


例如 ， 下 面 列举 了 几 个 不 同 语言 对 应 不 同 的 字符 串 资 源 文件 。 


美语 (默认 区 域 语言 ) ” /values/strings.xml : 


<?xml version="1.0" encoding="utf-8"?> 
<resources> 
<string name="title">My Application</string> 
<string name="hello_world">Hello World!</string> 
</resources> 


西班牙 语 ， /values-es/strings.xml : 


«?xml version="1.0" encoding="utf-8"?> 

<resources> 
«string name="title">Mi Aplicaciónc/string» 
«string name="hello_world">Hola Mundo!</string> 


</resources> 


法 语 ， /values-fr/strings.xml : 


<?xml version="1.0" encoding="utf-8"?> 
<resources> 
<string name="title">Mon Application</string> 
<string name="hello_world">Bonjour le monde !</string> 


</resources> 


Note : 可 以 在 任何 资源 类 型 中 使 用 区 域 修饰 词 (或 者 任何 配置 修饰 符 )， 比 如 为 bitmap 提 
供 本 地 化 的 版 本 ， 更 多 信息 见 Localization。 


E xg 
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我 们 可 以 在 源 代 码 和 其 他 XML 文件 中 通过 <string> THN name 属性 来 引用 自己 的 字符 串 资 
Jg. o 


在 源 代 码 中 可 以 通过 R.string.«string name» 语法 来 引用 一 个 字符 串 资源 ， 很 多 方法 都 可 以 通 
过 这 种 方式 来 接受 字符 囊 。 


例如 : 


// Get a string resource from your app's Resources 
String hello = getResources().getString(R.string.hello world); 


// Or supply a string resource to a method that requires a string 


TextView textView - new TextView(this); 
textView.setText(R.string.hello world); 


在 其 他 XML 文件 中 ， 每 当 XML 属 性 要 接受 一 个 字符 串 值 时 ， 你 都 可 以 通 
过 @string/<string_name> 语法 来 引 用 字符 串 资源 。 


例如 : 


适 配 不 同 的 语言 


Qu 


«TextView 
android:layout width-"wrap content" 
android:layout height-"wrap content" 
android: text="@string/hello_world" /> 


64 


适 配 不 同 的 屏幕 


编写 :Lin-H - 原文 :http://developer.android.com/training/basics/supporting- 
devices/screens.html 


Android 用 尺寸 和 分 辨 率 这 两 种 常规 属性 对 不 同 的 设备 屏幕 加 以 分 类 。 我 们 应 该 想到 自己 的 
app 会 被 安装 在 各 种 屏幕 尺寸 和 分 辩 率 的 设备 中 。 这 样 ，app 中 就 应 该 包含 一 些 可 选 资源 ， 针 
对 不 同 的 屏幕 尺寸 和 分 辨认 ， 来 优化 其 外 观 。 


e 有 4 种 普遍 尺寸 : 小 (small)， 普 通 (normal)， 大 (large)， 起 大 (xlarge) 
e 4 种 普遍 分 辨 率 : 低 精 度 (ldpi), 中 精度 (mdpi), 高 精度 (hdpi), 超 高 精度 (xhdpi) 


声明 针对 不 同 屏 幕 所 用 的 layout 和 bitmap， 必 须 把 这 些 可 选 资源 放置 在 独立 的 目录 中 ， 这 与 适 
配 不 同 语言 时 的 做 法 类 似 。 


同样 要 注意 屏幕 的 方向 (横向 或 纵向 ) 也 是 一 种 需要 考虑 的 屏幕 尺寸 变化 ， 因 此 许多 app 会 修改 
layout， 来 针对 不 同 的 屏幕 方向 优化 用 户 体 验 。 


创建 不 同 的 layout 


为 了 针对 不 同 的 屏幕 去 优化 用 户 体验 ， 我 们 需要 为 每 一 种 将 要 支持 的 屏幕 尺寸 创建 唯一 的 
XML x fF ° 每 一 种 layout 需 要 保存 在 相应 的 资源 目录 中 ， 目 录 以 -<screen size> 为 后 级 命名 。 
例如 ， 对 大 尺寸 屏幕 (large screens)， 一 个 唯一 的 layout 文 件 应 该 保存 在 res/1ayout- 

large/ 中 。 


Note: 为 了 匹配 合适 的 屏幕 尺寸 Android 会 自动 地 测量 我 们 的 layout 文 件 。 所 以 不 需要 因 不 
同 的 屏幕 尺寸 去 担心 Ul 元 素 的 大 小 ， 而 应 该 专注 于 layout 结 构 对 用 户 体验 的 影响 。( 比 如 
关键 视图 相对 于 同 级 视图 的 尺寸 或 位 置 ) 


例如 ， 这 个 工程 包含 一 个 默认 layout 和 一 个 适 配 大 屏幕 的 layout : 


MyProject/ 
res/ 
layout/ 
main. xml 
layout-large/ 
main. xml 


layout 文 件 的 名 字 必 须 完 全 一 样 ， 为 了 对 相应 的 屏幕 尺寸 提供 最 优 的 Ul， 文 件 的 内 容 不 同 。 


如 平常 一 样 在 app 中 简单 引用 : 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
setContentView(R.layout.main); 


系统 会 根据 app 所 运行 的 设备 屏幕 尺寸 ， 在 与 之 对 应 的 layout 目 录 中 加 载 layout。 更 多 关于 
Android 如 何 选 择 恰当 资源 的 信息 ， 详 见 Providing Resources ° 


另 一 个 例子 ， 这 一 个 工程 中 有 为 适 配 横向 屏幕 的 layout: 


MyProject/ 
res/ 
layout/ 
main. xml 
layout -land/ 
main. xml 


BRIA * layout/main.xml 文件 用 作 坚 屏 的 layout。 


果 想 给 横 屏 提供 一 个 特殊 的 layout， 也 适 配 于 大 屏幕 ， 那 么 则 需要 使 用 large 和 land 修饰 


符 。 
MyProject/ 
res/ 

layout/ 4 default (portrait) 
main. xml 

layout -land/ # landscape 
main. xml 

layout-large/ # large (portrait) 
main. xml 


layout-large-land/ # large landscape 
main. xml 


Note:Android 3.24% o 义 屏 Bo 高 级 方法 ， 它 允许 我 们 根据 屏幕 最 小 长 
度 和 宽度 ， 为 各 种 屏幕 尺寸 指定 与 密 关 的 layout 资 源 。 这 节 课 程 不 会 涉及 这 一 新 技 
术 ， 更 多 信息 详 见 Designing for et Screens。 


创建 不 同 的 bitmap 


我 们 应 该 为 4 种 普遍 分 状 率 : 低 ， 中 ， 高 ， 超 高 精度 ， 都 提供 相 适 配 的 bitmap 资 源 。 这 能 使 我 们 
的 app 在 所 有 屏幕 分 辨 率 中 都 能 有 良好 的 画 质 和 效果 。 


要 生成 这 些 图 像 ， 应 该 从 原始 的 矢量 图 像 资 源 着 手 ， 然 后 根据 下 列 尺 寸 比 例 ， 生 成 各 种 
下 的 图 像 。 


YS 


AR 


e xhdpi: 2.0 

hdpi: 1.5 

mdpi: 1.0 (基准 ) 
Idpi: 0.75 


这 意味 着 ， 如 果 针 对 xhdpi 的 设备 生成 了 一 张 200x200 的 图 像 ， 那 么 应 该 为 hdpi 生 成 150x150， 
为 mdpi 生 成 100x100, 和 为 Idpi 生 成 75x75 的 图 片 资 源 。 


然后 ， 将 这 些 文件 放 入 相应 的 drawable 资 源 目录 中 : 


MyProject/ 
res/ 

drawable-xhdpi/ 
awesomeimage.png 

drawable-hdpi/ 
awesomeimage.png 

drawable-mdpi/ 
awesomeimage.png 

drawable-ldpi/ 
awesomeimage.png 


任何 时 候 ， 当 引用 @drawable/awesomeimage 时 系 统 会 根据 屏幕 的 分 辩 兴 选择 恰当 的 bitmap ° 


Note: 低 密度 (Ildpi) 资 源 是 非 作 要 的 ， 当 提供 了 hdpi 的 图 像 ， 系 统 会 把 hdpi 的 图 像 按 比例 缩 
小 一 半 ， 去 适 配 ldpi 的 屏幕 。 


更 多 关于 为 app 创 建 图 标 assets 的 信息 和 指导 ， 详 见 Iconography design ° 


适 配 不 同 的 系统 版 本 


编写 :Lin-H - 原文 :http://developer.android.com/training/basics/supporting- 
devices/platforms.html 


新 的 Android 版 本 会 为 我 们 的 app 提 供 更 棒 的 APls， 但 我 们 的 app 仍 应 支持 昌 版 本 的 Android ， 
直到 更 多 的 设备 升级 到 新 版 本 为 止 。 这 节 课 程 将 展示 如 何在 利用 新 的 APls 的 同时 仍 支 持 旧 版 
本 Android 。 


Platform Versions 的 控制 面板 会 定时 更 新 ， 通 过 统计 访问 Google Play Store 的 设备 数量 ， 来 
显示 运行 每 个 版 本 的 安 草 设备 的 分 布 。 一 般 情 况 下 ， 在 更 新 app 至 最 新 Android 版 本 时 ， 最 好 
先 保证 新 版 的 app 可 以 支持 90% 的 设备 使 用 。 


Tip: 为 了 能 在 几 个 Android 版 本 中 都 能 提供 最 好 的 特性 和 功能 ， 应 该 在 我 们 的 app 中 使 
用 Android Support Library ， 它 能 使 我 们 的 app 能 在 昌平 台 上 使 用 最 近 的 几 个 平台 的 
APIs ° 


指定 最 小 和 目标 API 级 别 


AndroidManifest.xml 文 件 中 描述 了 我 们 的 app 的 细节 及 app 支 持 哪些 Android 版 本 。 具 体 来 

说 ， <uses-sdk> 元 素 中 的 minsdkversion 和 targetSdkVersion 属性 ， 标 明 在 设计 和 测试 app 
时 ， 最 低 兼 容 API 的 级 别 和 最 高 适用 的 API 级 别 (这 个 最 高 的 级 别 是 需要 通过 我 们 的 测试 的 )。 例 
如 : 


«manifest xmlns:android-"http://schemas.android.com/apk/res/android" ... » 
«uses-sdk android:minSdkVersion="4" android:targetSdkVersion-z"15" /> 


«/manifest» 


随 着 新 版 本 Android 的 发 布 ， 一 些 风格 和 行为 可 能 会 改变 ， 为 了 能 使 app 能 利用 这 些 变化 ， 而 
且 能 适 配 不 同 风格 的 用 户 的 设备 ， 我 们 应 该 将 targetSdkVersion 的 值 尽量 的 设置 与 最 新 可 用 
的 Android 版 本 匹配 。 


运行 时 检查 系统 版 本 


Android 在 Build 常 量 类 中 提供 了 对 每 一 个 版 本 的 唯一 代号 ， 在 我 们 的 app 中 使 用 这 些 代 号 可 以 
建立 条 件 ， 保 证 依赖 于 高 级 别 的 API 的 代码 ， 只 会 在 这 些 API 在 当前 系统 中 可 用 时 ， 才 会 执 
行 。 


private void setUpActionBar() { 
// Make sure we're running on Honeycomb or higher to use ActionBar APIs 
if (Build.VERSION.SDK INT >= Build.VERSION CODES.HONEYCOMB) { 
ActionBar actionBar - getActionBar(); 
actionBar.setDisplayHomeAsUpEnabled(true); 


Note: 当 解析 XML 资源 时 ，Android 会 忽略 当前 设备 不 支持 的 XML 属性 。 所 以 我 们 可 以 安 
全 地 使 用 较 新 版 本 的 XML 属性 ， 而 不 需要 担心 日 版 本 Android 遇 到 这 些 代码 时 会 前 溃 。 例 
如 如 果 我 们 设置 targetSdkversion="11" ，app 会 在 Android 3.0 或 更 高 时 默认 包 

含 ActionBar。 然 后 添加 menu items 到 action bar 时 ， 我 们 需要 在 自己 的 menu XML 资源 中 
设置 android:showAsAction-"ifRoom" 。 在 跨 版 本 的 XML 文件 中 这 么 做 是 安全 的 ， 因 为 昌 
版 本 的 Android 会 简单 地 忽略 showAsAction 属性 (就 是 这 样 ， 你 并 不 需要 用 到 res/menu- 
vii/ 中 单独 版 本 的 文件 ) 。 


使 用 平台 风格 和 主题 
Android 提 供 了 用 户 体 验 主题 ， 为 app 提 供 基础 操作 系统 的 外 观 和 体验 。 这 些 主题 可 以 在 


manifest 文 件 中 被 应 用 于 app 中 。 通 过 使 用 内 置 的 风格 和 主题 ， 我 们 的 app 自 然 地 随 着 Android 
新 版 本 的 发 布 ， 自 动 适 配 最 新 的 外 观 和 体验 . 


使 activity 看 起 来 像 对 话 框 : 


«activity android: theme="@android:style/Theme.Dialog"> 
使 activity 有 一 个 透明 背景 
«activity android:theme-"Qandroid:style/Theme.Translucent"- 


应 用 在 /res/values/styles.xml 中 定义 的 自 定义 主题 : 


«activity android:theme-"Qstyle/CustomTheme"- 


使 整个 app 应 用 一 个 主题 (全 部 activities) 在 元 素 中 添加 android:theme 属性 : 


«application android: theme="@style/CustomTheme"> 


更 多 关于 创建 和 使 用 主题 ， 详 见 Styles and Themes » 
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适 配 不 同 的 系统 版 本 
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'& 3E Activity 49 4-4» J5] 3 


J. sc: http://developer.android.com/training/basics/activity-lifecycle/index.html 


当 用 户 导 航 、 退 出 和 返回 您 的 应 用 时 ， 应 用 中 的 Activity 实例 将 在 其 生命 周期 中 转换 不 同 状 
态 。 例 如 ， 当 您 的 Activity 初 次 开始 时 ， 它 将 出 现在 系统 前 台 并 接收 用 户 焦点 。 在 这 个 过 程 
中 ，Android 系统 会 对 Activity 调 用 一 系列 生命 周期 方法 ， 通 过 这 些 方 法 ， 您 可 以 设置 用 户 界面 
和 其 他 组 件 。 如 果 用 户 执 行 开始 另 一 Activity 或 切换 至 另 一 应 用 的 操作 ， 当 其 进入 后 台 (在 其 
中 Activity 不 再 可 见 ， 但 实例 及 其 状态 完整 保留 ) ， 系 统 会 对 您 的 Activity 调 用 另外 一 系列 生命 
周期 方法 。 


在 生命 周期 回调 方法 内 ， 您 可 以 声明 用 户 离 开 和 再 次 进入 Activity 时 的 Activity 行 为 。 比 如 ， 如 
果 您 正 构建 流 视频 播放 器 ， 当 用 户 切换 至 另 一 应 用 时 ， 您 可 能 要 暂停 视频 或 终止 网 络 连接 。 
当 用 户 返 回 时 ， 您 可 以 重新 连接 网 络 并 允许 用 户 从 同一 位 置 继续 播放 视频 。 


本 课 讲述 每 个 Activity QM 重要 生命 周期 回调 方法 以 及 您 如 何 使 用 这 些 方法 以 使 您 的 
Activity 按 照 用 户 预 期 进行 并 且 当 您 的 Activity 不 需要 它们 时 不 会 消耗 系统 资源 。 


完整 的 Demo 示 例 : ActivityLifecycle.zip 


Lessons 


e 局 动 与 销毁 Activity 


学 习 有 关 Activity 生 命 周 期 、 用 户 如 何 启动 您 的 应 用 以 及 如 何 执行 基本 Activity 创 建 操 作 的 
基础 知识 。 


e 暂停 与 恢复 Activity 
学 习 Activity 暂 停 时 〈 部 分 隐藏 ) 和 继续 时 的 情况 以 及 您 应 在 这 态 变 化 期 间 执 行 的 操 
作 。 


e 停止 与 重启 Activity 
学 习 用 户 完全 离开 您 的 Activity 并 返回 到 该 Activity 时 发 生 的 情况 。 
e 重新 创建 Activity 
学 习 您 的 Activity 被 销毁 时 的 情况 以 及 您 如 何 能 够 根据 需要 重新 构建 Activity 。 


Ja 35 5 4 € Activity 


编写 :kesenhoo - Æ X:http://developer.android.com/training/basics/activity- 
lifecycle/starting.html 


不 同 于 使 用 maino 方法 启动 应 用 的 其 他 编程 范例 ，Android 系统 会 通过 调用 对 应 于 其 生命 周 
期 中 特定 阶段 的 特定 回调 方法 在 Activity 实例 中 启动 代码 。 有 一 系列 可 启动 Activity 的 回调 方 
法 ， 以 及 一 系列 可 分 解 Activity 的 回调 方法 。 


本 课程 概述 了 最 重要 的 生命 周期 方法 ， 并 向 您 展示 如 何 处 理 创 建 Activity 新 实例 的 第 一 个 生命 
周期 回调 。 


了 解 生 命 周期 回调 


在 Activity 的 生命 周期 中 ， 系 统 会 按 类 似 于 阶梯 金字 塔 的 顺序 调用 一 组 核心 的 生命 周期 方法 。 
也 就 是 说 ，Activity 生 命 周期 的 每 个 阶段 就 是 金字 塔 上 的 一 阶 。 当 系 统 创 OA 时 ， 
每 个 回调 方法 会 将 Activity 状 态 向 顶端 移动 一 阶 。 人 金字塔 的 顶端 是 Activity 在 前 台 运 行 并 且 用 户 
可 以 与 其 交互 的 时 间 点 。 


当 用 户 开 始 离开 Activity 时 ， 系 统 会 调用 其 他 方法 在 金字 塔 中 将 Activity 状 态 下 移 ， 从 而 销毁 
Activity。 在 有 些 情况 下 ，Activity 将 只 在 金字 塔 中 部 分 下 移 并 等 待 (比如 ， 当 用 户 切 换 到 其 他 
应 用 时 ) ，Activity 可 从 该 点 开始 移 回 顶端 (如 果 用 户 返 回 到 该 Activity) ， 并 在 用 户 停止 的 位 
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"— 续 "状态 移动 一 wp M. 回调 方法 。Activity 还 
从 “暂停 "和 “停止 "状态 回 到 继续 状态 。* 


根据 Activity 的 复杂 程度 ， 您 可 外 e 周期 方法 。 但 是 ， 了 解 每 个 方法 并 实现 
确保 您 的 应 用 按照 用 户 期 望 的 方式 运行 的 方法 非常 重要 。 正 确实 现 您 的 Activity 生 命 周 期 方法 
可 确保 您 的 应 用 按照 以 下 几 种 方式 良好 运行 ， 包 括 : 


。 如 果 用 户 在 使 用 您 的 应 用 时 接听 来 电 或 切换 到 另 一 个 应 用 ， 它 不 会 甬 溃 。 
e 在 用 户 未 主动 使 用 它 时 不 会 消耗 宝贵 的 系统 资源 。 

e 如 果 用 户 离开 您 的 应 用 并 稍 后 返回 ， 不 会 丢失 用 户 的 进度 

e 当 屏 幕 在 横向 和 纵向 之 问 旋 转 时 ， 不 会 崩溃 或 丢失 用 户 的 进度 


正如 您 将 要 在 以 下 课程 中 要 学 习 的 ， 有 Activity 会 在 图 1 所 示 不 同 状态 之 间 过 渡 的 几 种 情况 。 
但 是 ， 这 些 状态 中 只 有 三 种 可 以 是 静态 。 也 就 是 说 ，Activity 只 能 在 三 种 状态 之 一 下 存在 很 长 
时 间 。 


e Resumed : 在 这 种 状态 下 ，Activity 处 于 前 人 台 ， 且 用 户 可 以 与 其 交互 。 (有 时 也 称 为 “ 运 
行 " 状 态 。) 

e Paused : 在 这 种 状态 下 ，Activity 被 在 前 台中 处 于 半 透 明 状态 或 者 未 覆盖 整个 屏幕 的 另 一 
个 Activity 一 部 分 阻挡 。 暂 停 的 Activity 不 会 接收 用 户 输入 并 且 无 法 执行 任何 代码 。 

e Stopped : 在 这 种 状态 下 ， LAG mU 隐藏 并 且 对 用 户 不 可 见 ; 它 被 视 为 处 于 后 台 。 
停止 时 ，Activity 实 例 及 其 诸如 成 员 变 量 等 所 有 状态 信息 将 保留 ， 但 它 无 法 执行 任何 代 
码 。 


其 他 状态 (“创建 "和 "“ 开 à) 是 BEA ! 


其 它 状态 (Created 5 Started) 242 H 4 tA > 4 VLA i8 DRE S 4r AMAA IAM 
这 些 状 态 快速 移 到 下 一 个 状态 。 也 就 是 说 ， 在 系统 调用 onCreate()) 之 后 ， 它 会 快速 调用 
onStart())， 紧 接着 快速 调用 onResume()) 。 


基本 生命 周期 部 分 到 此 为 止 。 现 在 ， 您 将 开始 学 习 特 定 生命 周期 行为 的 一 些 知 识 。 


o ta n th pe = u 
指定 程序 首次 启动 的 Activity 
当 用 户 从 主 界 面 点 击 程 序 图 标 时 ， 系 统 会 调用 app 中 被 声明 为 "launcher" (or "main") activity 中 
的 onCreate() 方 法 。 这 个 Activity 被 用 来 当 作 程序 的 主要 进入 点 。 
我 们 可 以 在 AndroidManifest.xml 中 定义 作为 主 activity 的 activity。 


这 个 main activity 必 须 在 manifest 使 用 包括 marn action 与 Launcher Category 的 <intent- 
filter> 标签 来 声明 。 例 如 : 


«activity android:name=".MainActivity" android: label="@string/app_name"> 
<intent-filter> 
<action android:name="android.intent.action.MAIN" /> 
«category android:name-"android.intent.category.LAUNCHER" /> 
</intent-filter> 
</activity> 


Note: 25 44% M Android SDK 工 具 来 创建 Android 工 程 时 ， 工 程 中 就 包含 了 一 个 默认 的 声明 
有 这 个 filter 的 activity 类 。 


如 果 程 序 中 没有 声明 了 MAIN action 或 者 LAUNCHER category 的 activity， 那 么 在 设备 的 主 罚 
面 列 表 里 面 不 会 呈现 app 图 标 。 


创建 一 个 新 的 实例 


大 多 数 app 包 括 多 个 activity， 使 用 户 可 以 执行 不 同 的 动作 。 不 论 这 个 activity 是 当 用 户 点 击 应 用 
图 标 创建 的 main activtiy 还 是 为 了 响应 用 户 行 为 而 创建 的 其 他 activity， 系 统 都 会 调用 新 activity 
实例 中 的 onCreate() 方 法 。 


我 们 必须 实现 onCreate() 方 法 来 执行 程序 启动 所 需要 的 基本 如 辑 。 例 如 可 以 在 onCreate() 方 法 
中 定义 U 以 及 实例 化 类 成 员 变量 。 


例如 : 下 面 的 onCreate() 方 法 演示 了 为 了 建立 一 个 activity 所 需要 的 一 些 基 础 操作 。 如 声明 UI 元 
素 ， 定 义 成 员 变量 ， 配 置 Ul 等 。(onCreale 里 面 尽量 少 做 事情 ， 避 免 程 序 启 动 太 久 都 看 不 到 界 
面 ) 


TextView mTextView; // Member variable for text view in the layout 


@Override 
public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


// Set the user interface layout for this Activity 
// The layout file is defined in the project res/layout/main activity.xml file 
setContentView(R.layout.main activity); 


// Initialize member TextView so we can manipulate it later 
mTextView - (TextView) findViewById(R.id.text message); 


// Make sure we're running on Honeycomb or higher to use ActionBar APIs 
if (Build.VERSION.SDK INT >= Build.VERSION CODES.HONEYCOMB) { 
// For the main activity, make sure the app icon in the action bar 
// does not behave as a button 
ActionBar actionBar - getActionBar(); 
actionBar.setHomeButtonEnabled(false); 


Caution : 用 SDK_INT 来 避免 日 的 系统 调用 了 只 在 Android 2.0 (API level 5) 或 者 更 新 
的 系统 可 用 的 方法 (上述 if 条 件 中 的 代码 ) 。 旧 的 系统 调用 了 这 些 方法 会 抛 出 一 个 运行 时 


一 旦 onCreate 操作 完成 ， 系 统 会 迅速 调用 onStart() 与 onResume() 方 法 。 我 们 的 activity 不 会 
在 Created 或 者 Started 状 态 停 留 。 技 术 上 来 说 , activity 在 onStart() 被 调用 后 开始 被 用 户 可 见 ， 
但 是 onResume() 会 迅速 被 执行 使 得 activity 停 留 在 Resumed 状 态 ， 直 到 一 些 因素 发 生变 化 才 
会 改变 这 个 状态 。 例 如 接收 到 一 个 来 电 ， 用 户 切 换 到 另外 一 个 activity， 或 者 是 设备 屏幕 关 

闭 。 


在 后 面 的 课程 中 ， 我 们 将 看 到 其 他 方法 是 如 何 使 用 的 ，onStart() 与 onResume() 在 用 户 从 
Paused 或 Stopped 状 态 中 恢复 的 时 候 非 常 有 用 。 


Note: onCreate() 方法 包含 了 一 个 参数 叫做 savedlnstanceState， 这 将 会 在 后 面 的 课程 - 
重新 创建 activity 涉 及 到 。 
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Figure 2. 上 图 显示 了 onCreate(), onStart() 和 onResume() 是 如 何 执行 的 。 当 这 三 个 顺序 执行 
的 回调 函数 完成 后 ，activity 会 到 达 Resumed 状 态 。 
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48 9X Activity 


activity 的 第 一 个 生命 周期 回调 函数 是 onCreate(), 它 最 后 一 个 回调 是 onDestroy(). 当 收 到 需要 将 
该 activity 彻 底 移 除 的 信号 时 ， 系 统 会 调用 这 个 方法 。 


大 多 数 app 并 不 需要 实现 这 个 方法 ， 因 为 局 部 类 的 references 会 随 着 activity 的 销毁 而 销毁 ， 并 
且 我 们 的 activity 应 该 在 onPause() 与 onStop() 中 执行 清除 activity 资 源 的 操作 。 然 而 ， 如 果 
activity 含 有 在 onCreate 调 用 时 创建 的 后 台 线 程 ， 或 者 是 其 他 有 可 能 导致 内 存 泄漏 的 资源 ， 则 

应 该 在 DnDestroy() 时 进行 资源 清理 ， 杀 死 后 台 线 程 。 


@Override 
public void onDestroy() { 
super.onDestroy(); // Always call the superclass 


// Stop method tracing that the activity started during onCreate() 
android.os.Debug.stopMethodTracing(); 


Note: 除非 程序 在 onCreate() 方 法 里 面 就 调用 了 finish() 方 法 ， 系 统 通常 是 在 执行 了 
onPause() 与 onStop() 之 后 再 调用 onDestroy() 。 在 某 些 情况 下 ， 例 如 我 们 的 activity 只 是 
a 这 样 的 话 ， 需 
要 在 onCreate 里 面 调用 finish 方 法 ， 这 样 系统 会 直接 调用 onDestory， 跳 过 生命 周期 中 的 
其 他 方法 。 


ka 3h 5; 44 9x Activity 


TT 


暂停 与 恢复 Activity 


编写 :kesenhoo - 原文 :http://developer.android.com/training/basics/activity- 
lifecycle/pausing.html 


在 正常 使 用 app 时 ， 前 端的 activity 有 时 会 被 其 他 可 见 的 组 件 阻 塞 (obstructed)， 从 而 导致 当前 
的 activity 进 入 Pause 状 态 。 例 如 ， 当 打开 一 个 半 透 明 的 idi 时 (例如 以 对 话 框 的 形式 )， 之 前 
的 activity 会 被 暂停 。 只 要 之 前 的 activity 仍 然 被 部 分 可 见 ， 这 个 activity 就 会 一 直 处 于 Paused 状 


然而 ， 一 旦 之 前 的 activity 被 完全 阻塞 并 不 可 见 时 ， 则 其 会 进入 Stop 状 态 (将 在 下 一 小 节 讨 论 )。 


activity 一 旦 进入 paused 状 态 ， 系 统 就 会 调用 activity 中 的 onPause() 方 法 , 该 方法 中 可 以 停止 不 
aw 程 中 执行 的 操作 ， 如 暂停 视频 播放 ; 或 者 保存 那些 有 可 能 需要 长 期 保存 的 信 
。 如 果 用 户 从 暂停 状态 回 到 当前 activity， 系 统 应 该 恢复 那些 数据 并 执行 onResume() 方 法 。 


Note: 当 我 们 的 activity 收 到 调用 onPause() 的 信号 时 ， 那 可 能 意味 者 activity 将 被 暂停 一 段 
时 间 ， 并 且 用 户 很 可 能 回 到 我 们 的 activity。 然 而 ， 那 也 是 用 户 要 离开 我 们 的 activtiy 的 第 
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ii | Destroyed 
jos 1. 类 一 个 半 透 明 的 activity 阻 塞 activity 时 ， 系 统 会 调用 onPause() 方 法 并 且 这 个 activity 


停留 在 Paused 状态 (1). 如 果 用 户 在 这 个 activity 还 是 在 Paused 状态 时 回 到 这 个 activity， 系 
统 则 会 调用 它 的 onResume() (2). 


暂停 Activity 


当 系 统 调用 activity 中 的 onPause()， 从 技术 上 讲 ， 意 味 着 activity 仍 然 处 于 部 分 可 见 的 状态 .但 
更 多 时 候 意味 着 用 户 正在 离开 这 个 activity， 并 马上 会 进入 Stopped state. 通常 应 该 在 
onPause() 回 调 方法 里 面 做 以 下 事情 : 


e 停止 动画 或 者 是 其 他 正在 运行 的 操作 ， 那 些 都 会 导致 CPU 的 浪费 . 

e 提交 在 用 户 离开 时 期 待 保存 的 内 容 (例如 邮件 草稿 )， 

e 释放 系统 资源 ， 例 如 broadcast receivers, sensors (比如 GPS), 或 者 是 其 他 任何 会 影响 到 
电量 的 资源 。 


例如 , 如 果 程序 使 用 Camera,onPause() 会 是 一 个 比较 好 的 地 方 去 做 那些 释放 资源 的 操作 。 


@Override 
public void onPause() { 
super.onPause(); // Always call the superclass method first 


// Release the Camera because we don't need it when paused 
// and other activities might need to use it. 
if (mCamera != null) { 

mCamera.release() 

mCamera - null; 


通常 ， 不 应 该 使 用 onPause() 来 保存 用 户 改变 的 数据 (例如 卉 入 表格 中 的 个 人 信息 ) 到 永久 存储 
(File 或 者 DB) 上 。 仅 仅 当 确认 用 户 期 待 那些 改变 能 够 被 自动 保存 的 时 候 ( 例 如 正在 撰写 邮件 草 
稿 )， 才 把 那些 数据 存 到 永久 存储 。 但 是 ， 我 们 应 该 避免 在 onPause() 时 执行 CPU-intensive 的 
工作 ， 例 如 写 数据 到 DB， 因 为 它 会 导致 切换 到 下 一 个 activity 变 得 缓慢 (应 该 把 那些 heavy-load 
的 工作 放 到 onStop() 去 做 ) 。 


如 果 activity 实 际 上 是 要 被 Stop， 那 么 我 们 应 该 为 了 切换 的 顺畅 而 减少 在 OnPause() 方 法 里 面 
的 工作 量 。 


Note: 当 activity 处 于 暂停 状态 ，Activity 实 例 是 驻 留 在 内 存 中 的 ， 并 且 在 activity 恢复 的 时 
候 重 新 调用 。 我 们 不 需要 在 恢复 到 Resumed 状 态 的 一 系列 回调 方法 中 重新 初始 化 组 件 。 


A n a 
恢复 activity 
当 用 户 从 Paused 状 态 恢复 activity 时 ， 系 统 会 调用 onResume() 方 法 。 


请 注意 ， 系 统 每 次 调用 这 个 方法 时 ，activity 都 处 于 前 台 ， 包 括 第 一 次 创建 的 时 候 。 所 以 ， 应 

该 实现 onResume() 来 初始 化 那些 在 onPause 方 法 里 面 释放 掉 的 组 件 ， 并 执行 那些 activity 每 次 
进入 Resumed state 都 需要 的 初始 化 动作 (例如 开始 动画 与 初始 化 那些 只 有 在 获取 用 户 焦点 时 
才 需 要 的 组 件 ) 


下 面 的 onResume() 的 例子 是 与 上 面 的 onPause() 例 子 相 对 应 的 。 


停 与 恢复 Activity 


@Override 
public void onResume() { 
super.onResume(); // Always call the superclass method first 


// Get the Camera instance as the activity achieves full user focus 
if (mCamera == null) { 
initializeCamera(); // Local method to handle camera init 


80 


停止 与 重启 Activity 


编写 :kesenhoo - 原文 : http://developer.android.com/training/basics/activity- 
lifecycle/stopping.html 


恰当 的 停止 与 重启 我 们 eal 在 activity 生 命 周 期 中 ， 他 们 能 确保 用 户 感知 到 
程序 的 存在 并 不 会 丢失 他 们 的 进度 。 在 下 面 一 些 关 键 的 场景 中 会 涉及 到 停止 与 重启 : 


e FP 有 单 并 从 我 们 的 app 切 换 到 另外 一 个 app， 这 个 时 候 我 们 的 app 是 
被 停止 的 。 如 果 用 户 通过 手机 主 界面 的 启动 程序 图 标 或 者 最 近 使 用 程序 的 窗口 回 到 我 们 
的 app， 那 么 我 们 的 activity 会 重启 。 
e 用 户 在 我 们 的 app 里 面 执行 启动 一 个 新 activity 的 操作 ， 当 前 activity 会 在 第 二 个 activity 被 创 
建 后 stop。 如 果 用 户 点 击 back 按 钮 ， 第 一 个 activtiy 会 被 重启 。 
e 用 户 在 使 用 我 们 的 app 时 接收 到 一 个 来 电 通话 
Activity 类 提供 了 onStop() 与 onRestart() 方 法 来 允许 在 activity 停 止 与 重启 时 进行 调用 。 不 同 于 
暂停 状态 的 部 分 阻塞 Ul， 停 止 状态 是 Ul 不 再 可 见 并 且 用 户 的 焦点 转移 到 另 一 个 activity 中 . 


Note: 因为 系统 在 activity 停 止 时 会 在 内 存 中 保存 Activity 的 实例 ， 所 以 有 时 不 需要 实现 
onStop(),onRestart() 甚 至 是 onStart() 方 法 . 因为 大 多 数 的 activity 相 对 比较 简单 ，activity 会 
自己 停止 与 重启 ， 我 们 只 需要 使 用 onPause() 来 停止 正在 运行 的 动作 并 断 开 系统 资源 链 
接 。 
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Figure 1. 上 图 显示 : 当 用 户 离开 我 们 的 activity 时 ， 系 统 会 调用 onStop() 来 停止 activity (1). 这 
个 时 候 如 果 用 户 返 回 ， 系 统 会 调用 onRestart()(2), 之 后 会 迅速 调用 onStart()(3) 与 onResume() 
(4). 请 注意 : 无 论 什么 原因 导致 activity 停 止 ， 系 统 总 是 会 在 onStop() 之 前 调用 onPause() 方 
法 。 


停止 activity 


当 activity 调 用 onStop() 方 法 , activity 不 再 可 见 ， 并 且 应 该 释放 那些 不 再 需要 的 所 有 资源 。 一 旦 
activity 停 止 了 ， 系 统 会 在 需要 内 存 空间 时 挫 毁 它 的 实例 (和 栈 结构 有 关 ， 通 常 back 操 作 会 导致 
前 一 个 actrvity 被 销毁 )。 极 端 情况 下 ， 系 统 会 直接 杀 死 我 们 的 app 进 程 ， 并 不 执行 activity 的 
onDestroy() 回 调 方法 , 因此 我 们 需要 使 用 onStop() 来 释放 资源 ， 从 而 避免 内 存 泄漏 。( 这 点 需 
要 注意 ) 


尽管 onPause() 方 法 是 在 onStop() 之 前 调用 ， 我 们 应 该 使 用 onStop() 来 执行 那些 CPU intensive 
的 shut-down 操 作 ， 例 如 往 数 据 库 写 信 息 。 


例如 ， 下 面 是 一 个 在 onStop() 的 方法 里 面 保存 笔记 草稿 到 persistent storage 的 示例 : 


@Override 
protected void onStop() { 
super.onStop(); // Always call the superclass method first 


// Save the note's current draft, because the activity is stopping 
// and we want to be sure the current note progress isn't lost. 
ContentValues values - new ContentValues(); 
values.put(NotePad.Notes.COLUMN NAME NOTE, getCurrentNoteText()); 
values.put(NotePad.Notes.COLUMN NAME TITLE, getCurrentNoteTitle()); 


getContentResolver().update( 
muri, // The URI for the note to update. 
values, // The map of column names and new values to apply to them. 





null, // No SELECT criteria are used. 
null // No WHERE columns are used. 


); 


activity 已 经 停止 后 ，Activity 对 象 会 保存 在 内 存 中 ， 并 在 activity resume 时 被 重新 调用 。 我 们 不 
需要 在 恢复 到 Resumed state 状 态 前 重新 初始 化 那些 被 保存 在 内 存 中 的 组 件 。 系 统 同 样 保存 了 
每 一 个 在 布局 中 的 视图 的 当前 状态 ， 如 果 用 户 在 EditText 组 件 中 输入 了 text， 它 会 被 保存 ， 医 
此 不 需要 保存 与 恢复 它 。 


Note: 即使 系 indice stop 时 停止 这 个 activity， 它 仍然 会 保存 View 对 象 的 状态 (比如 
EditText 中 的 文字 ) 到 一 个 Bundle 中 ， 并 且 在 用 户 返 回 这 个 activity 时 恢复 它们 (下 一 小 节 会 


介绍 在 activity 销 毁 和 与 n 建立 时 如 何 使 用 Bundle 来 保存 其 他 数据 的 状态 ). 


启动 与 重启 activity 


当 activity 从 Stopped 状 态 回 到 前 台 时 ， 它 会 调用 onRestart(). 系 统 再 调用 onStart() 方 法 ， 
onStart() 方 法 会 在 每 次 activity 可 见 时 都 会 被 调用 。onRestart() 方 法 则 是 只 在 activity 从 stopped 
状态 恢复 时 才 会 被 调用 ， 因 此 我 们 可 以 使 用 它 来 执行 一 些 特殊 的 恢复 (restoration) 工 作 ， 请 注 
意 之 前 是 被 stopped 而 不 是 destrory。 


使 用 onRestart() 来 恢复 activity 状 态 是 不 太 常 见 的 ， 因 此 对 于 这 个 方法 如 何 使 用 没有 任何 的 
guidelines。 然 而 ， 因 为 onStop() 方 法 应 该 做 清除 所 有 activity 资 源 的 操作 ， 我 们 需要 在 重 局 
activtiy 时 重新 实例 化 那些 被 清除 的 资源 ， 同 样 , 我们 也 需要 在 activity 第 一 次 创建 时 实例 化 那些 
资源 。 介 于 上 面 的 原因 ， 应 该 使 用 onStart() 作 为 onStop() 所 对 应 方法 。 因 为 系统 会 在 创建 
activity 与 从 停止 状态 重启 activity 时 都 会 调用 onStart()。 也 就 是 说 ， 我 们 在 onStop 里 面 做 了 哪 
些 清除 的 操作 ， 就 该 在 onStart 里 面 重新 把 那些 清除 掉 的 资源 重新 创建 出 来 。 


例如 : 因为 用 户 很 可 能 在 回 到 这 个 activity 之 前 已 经 过 了 很 长 一 段 时 间 ， 所 以 onStart() 方 法 是 
一 个 比较 好 的 地 方 来 验证 某 些 必须 的 系统 特性 是 否 可 用 。 


@Override 
protected void onStart() { 
super.onStart(); // Always call the superclass method first 


// The activity is either being restarted or started for the first time 
// so this is where we should make sure that GPS is enabled 
LocationManager locationManager = 
(LocationManager) getSystemService(Context.LOCATION SERVICE); 
boolean gpsEnabled - locationManager.isProviderEnabled(LocationManager.GPS PROVIDE 
R); 


if (!gpsEnabled) { 
// Create a dialog here that requests the user to enable GPS, and use an intent 


// with the android.provider.Settings.ACTION LOCATION SOURCE SETTINGS action 
// to take the user to the Settings screen to enable GPS when they click "OK" 


} 


@Override 
protected void onRestart() { 
super.onRestart(); // Always call the superclass method first 


// Activity being restarted from stopped state 


} 
4 aT Bi 


娄 系 统 Destory 我 们 的 activity， 它 会 为 activity 调 用 onDestroy() 方 法 。 因 为 我 们 会 在 onStop 方 
法 里 面 做 释放 资源 的 操作 ， 那 么 onDestory 方 法 则 是 我 们 最 后 去 清除 那些 可 能 导致 内 存 泄漏 的 
地 方 。 因 此 需要 确保 那些 线程 都 被 destroyed 并 且 所 有 的 操作 都 被 停止 。 


停止 与 重启 Activity 
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重新 创建 Activity 


编写 :kesenhoo - 原文 : http://developer.android.com/training/basics/activity- 
lifecycle/recreating.html 


有 几 个 场景 中 ，Activity 是 由 于 正常 的 程序 行为 而 被 Destory 的 。 例 如 当 用 户 点 击 返回 按钮 或 者 
是 Activity 通 过 调用 finish() 来 发 出 停止 信号 。 系 统 也 有 可 能 会 在 Activity 处 于 stop 状 态 且 长 时 间 
不 被 使 用 ， 或 者 是 在 前 台 activity 需 要 更 多 系统 资源 的 时 关闭 后 台 进 程 ， 以 图 获取 更 多 的 内 
存 。 


当 Activity 是 因为 用 户 点 击 Back 按 钮 或 者 是 activity 通 过 调用 finish() 结 束 自 己 时 ， 系 统 就 丢失 了 
对 Activity 实 例 的 引用 ， 因 为 这 一 行为 意味 着 不 再 需要 这 个 activity 了 “。 然 而 ， 如 果 因 为 系统 资 
源 紧 张 而 导致 Activity 的 Destory > 系统 会 在 用 户 回 到 这 个 Activity 时 有 这 个 Activity 存 在 过 的 记 
录 ， 系 统 会 使 用 那些 保存 的 记录 数据 (描述 了 当 Activity 被 Destory 时 的 状态 ) 来 重新 创建 一 个 
新 的 Activity 实 例 。 那 些 被 系统 用 来 恢复 之 前 状态 而 保存 的 数据 被 叫做 "instance state" > Ex 
一 些 存 放 在 Bundle 对 象 中 的 key-value pairs。( 请 注意 这 里 的 描述 ， 这 对 理解 
onSavelnstanceState 执 行 的 时 刻 很 重要 ) 


Caution: 你 的 Activity 会 在 每 次 旋转 屏幕 时 被 destroyed 与 recreated。 当 屏幕 改变 方向 
时 ， 系 统 会 Destory 与 Recreate 前 台 的 activity， 因 为 屏幕 配置 被 改变 ， 你 的 Activity 可 能 需 
要 加 载 另 一 些 蔡 代 的 资源 (例如 layout). 


默认 情况 下 , 系统 使 用 Bundle 实例 来 保存 每 一 个 View( 视 图 ) 对 象 中 的 信息 (例如 输入 EditText 
中 的 文本 内 容 )。 因 此 ， 如 果 Activity 被 destroyed 与 recreated, 则 layout 的 状态 信息 会 自动 恢复 
到 之 前 的 状态 。 然 而 ，activity 也 许 存 在 更 多 你 想 要 恢复 的 状态 信息 ， 例 如 记录 用 户 Progress 
的 成 员 变 量 (membervariables)。 


Note: 为 了 使 Android 系 统 能 够 恢复 Activity 中 的 View 的 状态 ， 每 个 View 都 必须 有 一 个 唯 
一 ID， 由 android:id 定 义 。 


为 了 可 以 保存 额外 更 多 的 数据 到 saved instance state。 在 Activity 的 生命 周期 里 面 存 在 一 

外 的 回调 函数 ， 你 必须 重 写 这 个 函数 。 该 回调 函数 并 没有 在 前 面 课程 的 图 片 示例 中 显示 。 这 
个 方法 是 onSavelnstanceState() ， 当 用 户 离开 Activity 时 ， 系 统 会 调用 它 。 当 系统 调用 这 个 函 
数 时 ， 系 统 会 在 Activity 被 异常 Destory 时 传递 Bundle 对 象 ， 这 样 我 们 就 可 以 增加 额外 的 信息 
到 Bundle 中 并 保存 到 系统 中 。 若 系统 在 Activity 被 Destory 之 后 想 重新 创建 这 个 Activity 实 例 时 ， 
之 前 的 Bundle 对 象 会 (系统 ) 被 传递 到 你 我 们 activity 的 onRestorelnstanceState() 方 法 与 
onCreate() 方法 中 。 


allia — 1 -onSaveinstancestete0 —» (Í Destroyed O) 


一 | 
(.2 ) onCreate() 


Y 


Figure 2. 类 系统 开始 停止 Activity 时 ， 只 有 在 Activity 实 例会 需要 重新 创建 的 情况 下 才 会 调用 
到 onSavelnstanceState() (1) ， 在 这 个 方法 里 面 可 以 指定 额外 的 状态 数据 到 Bunde 中 。 如 果 这 
个 Activity 被 destroyed 然 后 这 个 实例 又 需要 被 重新 创建 时 ， 系 统 会 传递 在 (1) 中 的 状态 数据 到 
onCreate() (2) 与 onRestorelnstanceState()(3). 


(通常 来 说 ， 跳 转 到 其 他 的 activity 或 者 是 点 击 Home 都 会 导致 当前 的 actvity 执 行 
onSavelnstanceState， 因 为 这 种 情况 下 的 activity 都 是 有 可 能 会 被 destory 并 且 是 需要 保存 状态 
以 便 后 续 恢复 使 用 的 ， 而 从 跳 转 的 activity 点 击 back 回 到 前 一 个 activity， 那 么 跳 转 前 的 activity 
是 执行 退 栈 的 操作 ， 所 以 这 种 情况 下 是 不 会 执行 onSavelnstanceState 的 ， 因 为 这 个 gctivity 不 
可 能 存在 需要 重建 的 操作 ) 


保存 Activity 状 太 


当 我 们 的 activity 开 始 Stop， 系 统 会 调用 onSavelnstanceState() ，Activity 可 以 用 键 值 对 的 集 
合 来 保存 状态 信息 。 这 个 方法 会 默认 保存 Activity 视 图 的 状态 信息 ， 如 在 EditText 组 件 中 的 文 
AK ListView 的 滑动 位 置 。 


为 了 给 Activity 保 存 额外 的 状态 信息 ， 你 必须 实现 onSavelnstanceState() 并 增加 key-value 
pairs 到 Bundle 对 象 中 ， 例 如 : 


static final String STATE SCORE = "playerScore"; 
static final String STATE LEVEL - "playerLevel"; 


@Override 

public void onSaveInstanceState(Bundle savedInstanceState) { 
// Save the user's current game state 
savedInstanceState.putInt(STATE SCORE, mCurrentScore); 
savedInstanceState.putInt(STATE LEVEL, mCurrentLevel); 


// Always call the superclass so it can save the view hierarchy state 
super.onSaveInstanceState(savedInstanceState); 


Caution: 必须 要 调用 onSavelnstanceState() 方法 的 父 类 实现 ， 这 样 默认 的 父 类 实现 才 
能 保存 视图 状态 的 信息 。 


恢复 Activity 状 态 


当 Activity 从 Destory 中 重建 ， 我 们 可 以 从 系统 传递 的 Activity 的 Bundle 中 恢复 保存 的 状态 。 
onCreate() 与 onRestorelnstanceState() 回调 方法 都 接收 到 了 同样 的 Bundle， 里 面包 含 了 同 
样 的 实例 状态 信息 。 


由 于 onCreate() 方法 会 在 第 一 次 创建 新 的 Activity 实 例 与 重新 创建 之 前 被 Destory 的 实例 时 都 
被 调用 ， 我 们 必须 在 尝试 读 取 Bundle 对 象 前 检测 它 是 否 为 null。 如 果 它 为 null， 系 统 则 是 创建 
一 个 新 的 Activity 实 例 ， 而 不 是 恢复 之 前 被 Destory 的 Activity ° 


下 面 是 一 个 示例 : 演示 在 onCreate 方 法 里 面 恢复 一 些 数 据 : 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); // Always call the superclass first 


// Check whether we're recreating a previously destroyed instance 
if (savedInstanceState != null) { 
// Restore value of members from saved state 
mCurrentScore = savedInstanceState.getInt(STATE SCORE); 
mCurrentLevel = savedInstanceState.getInt(STATE LEVEL); 
y else f 
// Probably initialize members with default values for a new instance 


我 们 也 可 以 选择 实现 onRestorelnstanceState() ， 而 不 是 在 onCreate 方 法 里 面 恢复 数据 。 
onRestorelnstanceState() 方 法 会 在 onStart() 方法 之 后 执行 . 系统 仅仅 会 在 存在 需要 恢复 的 
状态 信息 时 才 会 调用 onRestorelnstanceState() ， 因 此 不 需要 检查 Bundle 是 否 为 null 。 


public void onRestoreInstanceState(Bundle savedInstanceState) { 
// Always call the superclass so it can restore the view hierarchy 
super.onRestoreInstanceState(savedInstanceState); 


// Restore state members from saved instance 
mCurrentScore - savedInstanceState.getInt(STATE SCORE); 
mCurrentLevel - savedInstanceState.getInt(STATE LEVEL); 


重新 创建 Activity 


Caution: 与 上 面 保 存 一 样 ， 总 是 需要 调用 OnRestorelnstanceState() 方 法 的 父 类 实现 ， 这 
样 黑 认 的 父 类 实现 才能 保存 视图 状态 的 信息 。 更 多 关于 运行 时 状态 改变 引起 的 recreate 我 
们 的 activity。 请 参考 Handling Runtime Changes. 
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使 用 Fragment 建 立 动态 UI 


编写 : fastcome1985 - 原 
x. : https://developer.android.com/training/basics/fragments/index.html 


为 了 在 Android 上 为 用 户 提供 动态 的 、 多 窗口 的 交互 体验 ， 需 要 将 UI 组 件 和 Activity 操作 封 
装 成 模块 进行 使 有 用， 这样 我 们 就 可 以 在 Activity 中 对 这 些 模块 进行 切入 切 出 操作 。 可 以 用 
Fragment 创建 这 些 模块 ，Fragment 3048 — 4-4 BAY Activity， 拥 有 自己 的 布局 (Layout) 并 
管理 自己 的 生命 周期 。 


Fragment 定义 了 自己 的 布局 后 ， 它 可 以 在 Activity 中 与 其 他 Fragment 生成 不 同 的 组 合 ， 从 
而 为 不 同 的 屏幕 尺寸 生成 不 同 的 布局 〈( 小 屏幕 一 次 也 许 只 能 显示 一 个 Fragment， 大 屏幕 则 可 
以 显示 更 多 ) 。 


本 章 将 展示 如 何 用 Fragment 创建 动 ARG ? 并 在 不 同 屏幕 尺寸 的 设备 上 优化 APP 的 用 P 体 
验 。 本 章 内 容 支持 Android 1.6 以 上 的 设备 。 


(完整 的 Demo 示例 : FragmentBasics.zip ) 


Lessons 


e 创建 Fragment 

学 习 如 何 创建 Fragment， 以 及 实现 其 生命 周期 内 的 基本 功能 。 
e 构建 有 弹性 的 UI 

学 习 如 何 针 对 不 同 的 屏幕 尺寸 用 Fragment 构建 不 同 的 布局 。 
e 与 其 他 Fragment 交互 


学 习 如 何在 Fragment 与 Activity 或 多 个 Fragment 间 进 行 交互 。 


创建 Fragment 


编写 : fastcome1985 - 原 
X : https://developer.android.com/training/basics/fragments/creating.html 


可 以 把 Fragment 想象 成 Activity 的 模块 ， 它 拥有 自己 的 生命 周期 、 接 收 输入 事件 ， 可 以 在 
Acvitity 运行 过 程 中 添加 或 者 移 除 (有 点 像 * 子 Activity”， 可 以 在 不 同 的 Activity 里 重复 使 

A) 。 这 一 课 教 我 们 将 学 习 继 承 Support Library 中 的 Fragment， 使 APP 在 Android 1.6 这 
样 的 低 版 本 上 仍 能 保持 兼容 。 


在 开始 之 前 ， 必 须 在 项 目 中 先 引 用 Support Library。 如 果 你 从 未 使 用 过 Support Library > "T 
根据 文档 设置 Support Library 在 项 目 中 使 用 V4 库 。 当 然 ， 也 可 以 使 用 包含 APP Bar 的 v7 
appcompat 库 。 该 库 兼 容 Android 2.1 (API level 7)， 同 时 也 包含 了 Fragment API ° 


创建 Fragment 类 


首先 从 Fragment 继承 并 创建 Fragment， 然 后 在 关键 的 生命 周期 方法 中 插入 代码 〈 就 和 在 处 
理 Activity 时 一 样 ) 。 


其 中 一 个 区 别 是 : 创建 Fragment 时 ， 必 须 重 写 onCreateView() 回调 方法 来 定义 布局 。 事 实 
上 ， 这 是 唯一 一 个 为 使 Fragment 运行 起 来 需要 重 写 的 回调 方法 。 比 如 ， 下 面 是 一 个 自 定义 布 
局 的 示例 Fragment : 


import android.os.Bundle; 

import android.support.v4.app.Fragment; 
import android.view.LayoutInflater; 
import android.view.ViewGroup; 


public class ArticleFragment extends Fragment { 
@Override 
public View onCreateView(LayoutInflater inflater, ViewGroup container, 
Bundle savedInstanceState) { 
// 拉 伸 该 Fragment 的 布局 
return inflater.inflate(R.layout.article view, container, false); 


和 Activity 一 样 ， 当 Fragment 从 Activity 添加 或 者 移 除 、 或 Activity 生命 周期 发 生变 化 时 ， 
Fragment 通过 生命 周期 回调 函数 管理 其 状态 。 例 如 ， 当 Activity 的 onPause() 被 调用 时 ， 它 
内 部 所 有 Fragment 的 onPause() 方法 也 会 被 触发 。 


更 多 关于 Fragment 的 声明 周期 和 回调 方法 ， 详 见 Fragments 开发 指南 . 


用 XML 将 Fragment 添加 到 Activity 


Fragments 是 可 重用 的 、 模 块 化 的 UI 组 件 。 每 个 Fragment 实例 都 必须 与 一 个 
FragmentActivity 关联 。 我 们 可 以 在 Activity 的 XML 布局 文件 中 逐个 定义 Fragment 来 实现 这 
种 关联 。 


注 : FragmentActivity 是 Support Library 提供 的 一 种 特殊 Activity， 用 于 处 理 API 11 版 
本 以 下 的 Fragment。 如 果 我 们 APP 中 的 最 低 版 本 大 于 等 于 11， 则 可 以 使 用 普通 的 
Activity ° 


以 下 是 一 个 XML 布局 的 例子 : 当 屏 幕 被 认为 是 "large" (用 目录 名 称 中 的 large 字符 来 区 
T) 时 ， 它 在 布局 中 增加 了 两 个 Fragment 。 


res/layout-large/news articles.xml 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:orientation-"horizontal" 
android:layout width-"fill parent" 
android: layout_height="fill_parent"> 


<fragment android:name="com.example.android.fragments.HeadlinesFragment" 
android: id="@t+tid/headlines_fragment" 
android: layout_weight="1" 
android: layout_width="O0dp" 
android:layout height-"match parent" /> 


«fragment android:name-"com.example.android.fragments.ArticleFragment" 
android:id-"Q-«-id/article fragment" 
android: layout_weight="2" 
android: layout_width="O0dp" 
android: layout_height="match_parent" /> 


</LinearLayout> 


提示 : 更 多 关于 不 同 屏幕 尺寸 创建 不 同 布局 的 信息 ， 请 阅读 兼容 不 同 屏幕 尺寸 。 


然后 将 这 个 布局 文件 用 到 Activity 中 。 


import android.os.Bundle; 
import android.support.v4.app.FragmentActivity; 


public class MainActivity extends FragmentActivity { 
@Override 
public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.news articles); 


创建 一 个 Fragment 


如 果 使 用 v7 appcompat 库 ，Activity 应 该 改 为 继承 自 AppCompatActivity， 
AppCompatActivity 是 FragmentActivity 的 子 类 (更 多 关于 这 方面 的 内 容 ， 请 阅读 添加 App 
Bar) 。 
i: 当 通 过 XML 布局 文件 的 方式 将 Fragment 添加 进 Activity 时 ，Fragment 是 不 能 被 
动态 移 除 的 。 如 果 想 要 在 用 户 交 互 的 时 候 把 Fragment 切入 与 切 出 ， 必 须 在 Activity 启动 
后 ， 再 将 Fragment 添加 进 Activity。 这 部 分 内 容 将 在 下 节 课 阐述 。 
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建立 灵活 动态 的 U| 


建立 灵活 动态 的 UI 


编写 : fastcome1985 - JR 
X : https://developer.android.com/training/basics/fragments/fragment-ui.html 


在 设计 支持 各 种 屏幕 尺寸 的 应 用 时 ， 你 可 以 在 不 同 的 布局 配置 中 重复 使 用 Fragment， 以 便 根 
据 相 应 的 屏幕 空间 提供 更 出 色 的 用 户 体验 。 


例如 ， 一 次 只 显示 一 个 Fragment 可 能 就 很 适合 手机 这 种 单 窗 格 界面 ， 但 在 平板 电脑 上 ， 你 可 


能 需要 设置 并 列 的 Fragment， 因 为 平板 电脑 的 屏幕 尺寸 较 宽 阔 ， 可 向 用 户 显示 更 多 信息 。 




















图 1 : 两 个 Fragment， 显 示 在 不 同 尺寸 屏幕 上 同一 Activity 的 不 同 配置 中 。 在 较 宽 阔 的 屏幕 
上 ， 两 个 Fragment 可 并 列 显示 ; 在 手机 上 ， 一 次 只 能 显示 一 个 Fragment， 因 此 必须 在 用 户 
导航 时 更 换 Fragment ° 


利用 FragmentManager 类 提供 的 方法 ， 你 可 以 在 运行 时 添加 、 移 除 和 替换 Activity 中 的 
Fragment， 以 便 为 用 户 提供 一 种 动态 体验 。 


在 运行 时 向 Activity 添加 Fragment 


你 可 以 在 Activity 运行 时 向 其 添加 Fragment， 而 不 用 像 上 一 课 中 介绍 的 那样 ， 使 用 
<fragment> 元 素 在 布局 文件 中 为 Activity 定义 Fragment。 如 果 你 打算 在 Activity 运行 周期 内 
更 改 Fragment， 就 必须 这 样 做 。 


要 执行 添加 或 移 除 Fragment 等 事务 ， 你 必须 使 用 FragmentManager 创建 一 个 
FragmentTransaction， 后 者 可 提供 用 于 执行 添加 、 移 除 、 替 换 以 及 其 他 Fragment 事务 的 
API ° 


如 果 Activity 中 的 Fragment 可 以 移 除 和 替换 ， 你 应 在 调用 Activity 的 onCreate() 方法 期 间 为 
Activity 添加 初始 Fragment(s) » 
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在 处 理 Fragment (特别 是 在 运行 时 添加 的 Fragment) 时 ， 请 谨 记 以 下 重要 规则 : 必须 在 布 
局 中 为 Fragment 提供 View 容器 ， 以 便 保存 Fragment 的 布局 。 


下 面 是 上 一 课 所 示 布 局 的 替代 布局 ， 这 种 布局 一 次 只 会 显示 一 个 Fragment。 要 用 一 个 
Fragment 替换 另 一 个 Fragment，Activity 的 布局 中 需要 包含 一 个 作为 Fragment 容器 的 空 
FrameLayout ° 


请 注意 该 文件 名 与 上 一 课 中 布局 文件 的 名 称 相同 ? 但 布局 目 录 没 有 large 这 一 限定 符 S 
此 ， 此 布局 会 在 设备 屏幕 小 于 “large” 的 情况 下 使 用 ， 原 因 是 尺寸 较 小 的 屏幕 不 适合 同时 显示 两 
个 Fragment。 


res/layout/news articles.xml: 


«FrameLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:id-"Q-id/fragment container" 
android:layout width-"match parent" 
android:layout height-"match parent" /> 


在 Activity 中 ， 用 Support Library API 调用 getSupportFragmentManager() 以 获取 
FragmentManager， 然 后 调用 beginTransaction() 创建 FragmentTransaction， 然 后 调用 
add() 添加 Fragment 。 


你 可 以 使 用 同一 个 FragmentTransaction 对 Activity 执行 多 Fragment 事务 。 当 你 准备 好 进行 
更 改 时 ， 必 须 调用 commit()。 


例如 ， 下 面 介绍 了 如 何 为 上 述 布局 添加 Fragment : 


import android.os.Bundle; 
import android.support.v4.app.FragmentActivity; 


public class MainActivity extends FragmentActivity { 


@Override 
public void onCreate(Bundle savedInstanceState) { 


super.onCreate(savedInstanceState); 
setContentView(R.layout.news articles); 


// 确认 Activity 使 用 的 布局 版 本 包含 fragment container FrameLayout 
if (findViewById(R.id.fragment container) != null) { 


// 不 过 ， 如 果 我 们 要 从 先前 的 状态 还 原 ， 则 无 需 执行 任何 操作 而 应 返回 ， 否 见 
// 就 会 得 到 重申 的 Fragment 
if (savedInstanceState != null) { 

return; 


// 创建 一 个 要 放 入 Activity 布局 中 的 新 Fragment 
HeadlinesFragment firstFragment = new HeadlinesFragment(); 


// 如 果 此 Activity 是 通过 Intent 发 出 的 特殊 指令 来 启动 的 ， 
该 Fragment 


A- 
a 


// 请 将 该 Intent 的 extras 以 参数 形式 传递 多 
firstFragment.setArguments(getIntent().getExtras()); 


// 将 该 Fragment ?&Je$|^fragment container" FrameLayout 中 


getSupportFragmentManager().beginTransaction() 
.add(R.id.fragment container, firstFragment).commit(); 


由 于 该 Fragment 已 在 运行 时 添加 到 FrameLayout 容器 中 ， 而 不 是 在 Activity 布局 中 通过 
<fragment> 元 素 进 行 定 义 ， 因 此 该 Activity 可 以 移 除 和 替换 这 个 Fragment。 


用 一 个 Fragment #4 4 — “+ Fragment 


替换 Fragment 的 步骤 与 添加 Fragment 的 步骤 相似 ， 但 需要 调用 replace() 方法 ， 而 非 
add() ° 


请 注意 ， 当 你 人 或 移 除 Fragment 等 Fragment 事务 时 ， 最 好 能 让 用 户 向 后 导航 和 " 撤 
消 ?所 做 更 改 。 要 通过 Fragment 事务 允许 用 户 向 后 导航 ， 你 必须 调用 addToBackStack()， 然 
后 再 执行 FragmentTransaction ° 
c 当 你 移 除 或 替换 Fragment 并 向 返回 堆栈 添加 事务 时 ， 已 移 除 的 Fragment 会 停止 
(而 不 是 销毁 ) 。 如 果 用 户 向 后 导航 ， 还 原 该 Fragment， 它 会 重新 启动 。 如 果 你 没有 向 
返回 扒 栈 添加 事务 ， 那 么 该 Fragment 在 移 除 或 替换 时 就 会 被 销毁 。 


替换 Fragment 的 示例 : 


// 创建 Fragment 并 为 其 添加 一 个 参数 ， 用 来 指定 应 显示 的 文章 
ArticleFragment newFragment = new ArticleFragment(); 
Bundle args - new Bundle(); 
args.putInt(ArticleFragment.ARG POSITION, position); 
newFragment.setArguments(args); 


FragmentTransaction transaction = getSupportFragmentManager().beginTransaction(); 





// 将 fragment container View 中 的 内 容 替 换 为 此 Fragment ° 





// 然后 将 该 事务 添加 到 返回 堆栈 ， 以 便 用 户 可 以 向 后 导航 


transaction.replace(R.id.fragment container, newFragment); 
transaction.addToBackStack(null); 


// 执行 事务 


transaction.commit(); 


addToBackStack() 方法 可 接受 可 选 的 字符 串 参 数 ， 来 为 事务 指定 独一无二 的 名 称 。 除 非 你 打 
算 使 用 FragmentManager.BackStackEntry API 执行 高 级 Fragment 操作 ， 和 否则 无 需 使 用 此 名 


与 其 他 Fragment 交互 


编写 : fastcome1985 - 原 
X : https://developer.android.com/training/basics/fragments/communicating.html 


为 了 重用 Fragment UI 组 件 ， 你 应 该 把 每 个 Fragment 都 构建 成 完全 自 包含 的 、 模 块 化 的 组 
件 ， 即 ， 定 义 它 们 自己 的 布局 与 行为 。 一 旦 你 定义 了 这 些 可 重用 的 Fragment， 你 就 可 以 通过 
应 用 程序 逻辑 让 它们 关联 到 Activity， 以 实现 整体 的 复合 Ul。 

通常 Fragment 之 间 可 能 会 需要 交互 ， 比 如 基于 用 户 事 件 的 内 容 变 更 。 所 有 Fragment 之 间 的 
交互 应 通过 与 之 关联 的 Activity 来 完成 。 两 个 Fragment 之 间 不 应 直接 交互 。 


定义 接口 


为 了 让 Fragment 与 包含 它 的 Activity 进行 交互 ， 可 以 在 Fragment 类 中 定义 一 个 接口 ， 并 在 
Activity 中 实现 。 该 Fragment 在 它 的 onAttach() 方法 生命 周期 中 获取 该 接口 的 实现 ， 然 后 调 
用 接口 的 方法 ， 以 便 与 Activity 进行 交互 。 (译注 : BPP > SHR Fragment 中 实现 了 
onAttach() 方法 ， 则 会 被 自动 调用 。 ) 


以 下 是 Fragment 与 Activity 交互 的 例子 : 


public class HeadlinesFragment extends ListFragment { 
OnHeadlineSelectedListener mCallback; 


Wf 
// (译注 : “容器 Activity" SF" ASH Fragment 的 Activity") 


容器 Activity 必须 实现 该 接口 





public interface OnHeadlineSelectedListener { 
public void onArticleSelected(int position); 


@Override 
public void onAttach(Activity activity) { 
super.onAttach(activity); 


// 确认 容器 Activity 已 实现 该 回调 接口 。 和 否则 ， 抛 出 异常 
iE] af 
mCallback - (OnHeadlineSelectedListener) activity; 
} catch (ClassCastException e) { 
throw new ClassCastException(activity.toString() 
* " must implement OnHeadlineSelectedListener"); 


现在 Fragment 可 以 通过 调用 mcallback ( OnHeadlineSelectedListener 接口 的 实例 ) 的 
onArticleselected() 方法 (也 可 以 是 其 它 方 法 ) 与 Activity 进行 消息 传递 。 


例如 ， 当 用 户 点 击 列表 条 目 时 ，Fragment 中 的 下 面 的 方法 将 被 调用 。Fragment 用 回调 接口 
将 事件 传递 给 父 Activity ^ 


@Override 

public void onListItemClick(ListView 1, View v, int position, long id) [f 
// 向 宿主 Activity 传送 事件 
mCallback.onArticleSelected(position); 


实现 接口 


为 了 接收 回调 事件 ， 宿 主 Activity 必须 实现 在 Fragment 中 定义 的 接口 。 


例如 ， 下 面 的 Activity 实现 了 上 面 例子 中 的 接口 。 


public static class MainActivity extends Activity 
implements HeadlinesFragment .OnHeadlineSelectedListener{ 


public void onArticleSelected(int position) { 
// 用 户 从 HeadlinesFragment 选择 了 一 篇 文章 的 标题 
// 在 这 里 做 点 什么 ， 以 显示 该 文章 


向 Fragment 传递 消息 


宿主 Activity 通过 findFragmentByld() 获取 Fragment 的 实例 ， 然 后 直接 调用 Fragment 的 
public 方法 向 Fragment 传递 消息 。 


例如 ， 假 设 上 面 所 示 的 Activity 可 能 包含 另 一 个 Fragment， 该 Fragment 用 于 展示 从 上 面 的 
回调 方法 中 返回 的 指定 的 数据 。 在 这 种 情况 下 ，Activity 可 以 把 从 回调 方法 中 接收 到 的 信息 传 
递 到 这 个 展示 数据 的 Fragment 。 


Fragments 


public static class MainActivity extends Activity 
implements HeadlinesFragment .OnHeadlineSelectedListener{ 


public void onArticleSelected(int position) { 
// MÈ} HeadlinesFragment 选择 了 一 篇 文章 的 标题 
// 在 这 里 做 点 什么 ， 以 显示 该 文章 


ArticleFragment articleFrag = (ArticleFragment) 
getSupportFragmentManager().findFragmentById(R.id.article fragment); 


if (articleFrag != null) { 
// € articleFrag 有 效 ， 则 表示 我 们 正在 处 理 两 格 布局 (two-pane layout) .... 


// 调用 ArticleFragment 的 方法 ， 以 更 新 其 内 容 
articleFrag.updateArticleView(position); 

) else { 
// 否则 ， 我 们 正在 处 理 单 格 布局 (one-pane layout) 。 此 时 需要 swap frags... 


// 创建 Fragment， 向 其 传递 包含 被 选 文章 的 参数 
ArticleFragment newFragment = new ArticleFragment(); 
Bundle args - new Bundle(); 
args.putInt(ArticleFragment.ARG POSITION, position); 
newFragment.setArguments(args); 


FragmentTransaction transaction = getSupportFragmentManager().beginTransac 


tion(); 
// 无 论 fragment container 视图 里 是 什么 ， 用 该 Fragment 替换 它 。 并 将 
// 该 事务 添加 至 回 栈 ， 以 便 用 户 可 以 往 回 导 航 (译注 : 回 栈 ， 即 Back Stack。 
// 在 有 多 个 Activity 的 APP 中 ， 将 这 些 Activity 按 创建 次 序 组 织 起 来 的 
// 栈 ， 称 为 回 栈 ) 
transaction.replace(R.id.fragment container, newFragment); 
transaction.addToBackStack(null); 
// 执行 事务 
transaction.commit(); 
} 
} 


数据 保存 


编写 :kesenhoo - /$ x-:http://developer.android.com/training/basics/data- 
storage/index.html 


虽然 可 以 在 onPause() 时 保存 一 些 信息 以 免 用 户 的 使 用 进度 被 丢失 ， 但 大 多 数 Android app 仍 
然 是 需 执 行 保存 数据 的 动作 。 大 多 数 较 好 的 apps 都 需要 保存 用 户 的 设置 信息 ， 而 且 有 一 些 
apps 必 须 维护 大 量 的 文件 信息 与 DB 信息 。 本 章节 将 介绍 Android 中 主要 的 数据 存储 方法 ， 包 
括 : 
e 保存 到 Preferences 
学 习 使 用 Shared Preferences 文 件 以 Key-Value 的 方式 保存 简要 的 信息 。 
e 保存 到 文件 
学 习 保 存 基 本 的 文件 。 
e 保存 到 数据 库 


学 习 使 用 SQLite 数 据 库 读 写 数据 。 


保存 到 Preference 


编写 :kesenhoo - 原文 :http://developer.android.com/training/basics/data-storage/shared- 


preferences.html 


当 有 一 个 相对 较 小 的 key-value 集 合 需 要 保存 时 ， 可 以 使 用 SharedPreferences APIs ° 
SharedPreferences 对 象 指向 一 个 保存 key-value pairs 的 文件 ， 并 为 读 写 他 们 提供 了 简单 的 方 
法 。 每 个 SharedPreferences 文件 均 由 framework 管 理 ， 其 既 可 以 是 私有 的 ， 也 可 以 是 共享 
的 。 这 节 课 会 演示 如 何 使 用 SharedPreferences APIs 来 存储 与 检索 简单 的 数据 。 


Note : SharedPreferences APIs 仅仅 提供 了 读 写 key-value 对 的 功能 ， 请 不 要 

与 Preference APls 相 混淆 。 后 者 可 以 帮助 我 们 建立 一 个 设置 用 户 配 置 的 页 面 (尽管 它 实 
际 上 是 使 用 SharedPreferences 来 实现 保存 用 户 配 置 的 )。 更 多 关于 Preference APls 的 信 
息 ， 请 参考 Settings 指南 。 


获取 SharedPreference 


我 们 可 以 通过 以 下 两 种 方法 之 一 创建 或 者 访问 shared preference 文件 : 


e getSharedPreferences() — 如 果 需 要 多 个 通过 名 称 参数 来 区 分 的 shared preference 文 件 ， 
名 称 可 以 通过 第 一 个 参数 来 指定 。 可 在 app 中 通过 任何 一 个 Context 执行 该 方法 。 

e getPreferences() — 当 activity 仅 需要 一 个 shared preference 文 件 时 。 因 为 该 方法 会 检索 
activity 下 上 默认 的 shared preference 文 件 ， 并 不 需要 提供 文件 名 称 。 


例 : 下 面 的 示例 在 一 个 Fragment 中 被 执行 ， 它 以 private 模 式 访问 名 为 
R.string.preference file key 的 shared preference 文 件 。 这 种 情况 下 ， 该 文件 仅 能 被 我 们 的 
app 访 问 。 


Context context = getActivity(); 
SharedPreferences sharedPref - context.getSharedPreferences( 
getString(R.string.preference file key), Context.MODE PRIVATE); 


应 以 与 app 相 关 的 方式 为 shared preference 文 件 命 名 ， 该 名 称 应 唯一 。 如 本 例 中 可 将 其 命名 为 


"com.example.myapp.PREFERENCE FILE KEY" ° 


当然 ， 当 activity 仅 需要 一 个 shared preference 文 件 时 ， 我 们 可 以 使 用 getPreferences() 方 法 : 


SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE PRIVATE); 


Caution: 如 果 创 建 了 一 个 MODE_WORLD READABLE Xi 
者 MODE WORLD WRITEABLE 模式 的 shared preference 文 件 ， 则 其 他 任何 app 均 可 通 
过 文件 名 访问 该 文件 。 


£ Shared Preference 


AT shared preferences 文件 ， 需 要 通过 执行 edit() 创 建 一 个 SharedPreferences.Editor ° 


通过 类 似 putlnt() 与 putString() 等 方法 传递 keys 与 values， 接 着 通过 commit() 提交 改变 . 


SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE PRIVATE); 
SharedPreferences.Editor editor - sharedPref.edit(); 
editor.putInt(getString(R.string.saved high score), newHighScore); 
editor.commit(); 


i€ Shared Preference 


为 了 从 shared preference 中 读 取 数 据 ， 可 以 通过 类 似 于 getlnt() 及 getString() 等 方法 来 读 取 。 
在 那些 方法 里 面 传 递 我 们 想 要 获取 的 value 对 应 的 key， 并 提供 一 个 默认 的 value 作 为 查找 的 key 
不 存在 时 函数 的 返回 值 。 如 下 : 


SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE PRIVATE); 
int defaultValue = getResources().getInteger(R.string.saved high score default); 
long highScore - sharedPref.getInt(getString(R.string.saved high score), default); 


保存 到 文件 


编写 :kesenhoo - 原文 :http://developer.android.com/training/basics/data- 
storage/files.html 


Android 使 用 与 其 他 平台 类 似 的 基于 磁盘 的 文件 系统 (disk-based file systems)。 本 课程 将 描述 
如 何在 Android 文 件 系 统 上 使 用 File 的 读 写 APIs 对 Andorid 的 flle system 进 行 读 写 。 


File 对 象 非 常 适合 于 流 式 顺序 数据 的 读 写 。 如 图 片 文件 或 是 网 络 中 交换 的 数据 等 。 


本 课程 将 会 演示 如 何在 app 中 执行 基本 的 文件 相关 操作 。 假 定 读者 已 对 linux 的 文件 系统 及 
java.io 中 标准 的 MO APIls 有 一 定 认识 。 


存储 在 内 部 还 是 外 部 


所 有 的 Android 设 备 均 有 两 个 文件 存储 区 域 : "internal" 4 "external" 。 这 两 个 名 称 来 自 于 早先 
的 Android 系 统 ， 当 时 大 多 设备 都 内 置 了 不 可 变 的 内 存 (internal storage) 及 一 个 类 似 于 SD 
card (external storage) 这 样 的 可 印 载 的 存储 部 件 。 之 后 有 一 些 设备 将 "internal" 5 "external" 
都 做 成 了 不 可 外 载 的 内 置 存 储 ， 虽 然 如 此 ， 但 是 这 一 整 块 还 是 从 逻辑 上 有 被 划分 

为 "internal" 与 "external" 的 。 只 是 现在 不 再 以 是 否 可 务 载 进行 区 分 了 。 下 面 列 出 了 两 者 的 区 

别 : 


e Internal storage: 


o 总 是 可 用 的 
o 这 里 的 文件 默认 只 能 被 我 们 的 app 所 访问 。 
o 当 用 户 和 载 app 的 时 候 ， 系 统 会 把 internal 内 该 app 相 关 的 文件 都 清除 干净 。 
o |Internal 是 我 们 在 想 确 保 不 被 用 户 与 其 他 app 所 访问 的 最 佳 存储 区 域 。 
e External storage: 


RAM 因为 用 户 有 时 会 通过 USB 存 储 模 式 挂 载 外 部 存储 器 ， 当 取 下 挂 载 
的 这 部 分 后 ， 就 无 法 对 其 进行 访问 了 。 

ea 因此 保存 在 这 里 的 文件 可 能 被 其 他 程序 访问 。 

o 当 用 户 镍 载 我 们 的 app 时 ， 系 统 仅仅 会 删除 external 根 目录 (getExternalFilesDir()) 
下 的 相关 文件 。 

o PX cum 需要 严格 的 访问 权限 并 且 和 希望 文件 能 够 被 其 他 app 所 共享 或 者 是 
允许 用 户 通过 电脑 访问 时 的 最 佳 存储 区 域 。 


VC 
"x 


Tip: 尽管 app 是 默认 被 安装 到 internal storage 的 ， 我 们 还 是 可 以 通过 在 程序 的 manifest 文 
件 中 声明 android:installLocation 属性 来 指定 程序 安装 到 external storage。 当 某 个 程序 的 
安装 文件 很 大 且 用 户 的 external storage 空 间 大 于 internal storage 时 ， 用 户 会 倾向 于 将 该 
程序 安装 到 external storage。 更 多 安装 信息 见 App Install Location ° 


ik External £4 8j 4x IR 


为 了 写 数据 到 external storage, 必须 在 你 manifest 文 件 中 请 
求 WRITE_EXTERNAL _STORAGE 权 限 : 


<manifest ...> 


«uses-permission android:name-"android.permission.WRITE EXTERNAL STORAGE" /> 


«/manifest» 


Caution: 目 前 ， 所 有 的 apps 都 可 以 在 不 指定 某 个 专门 的 权限 下 做 读 external storage? 7^ 
作 。 但 这 在 以 后 的 安 草 版 本 中 会 有 所 改变 。 如 果 我 们 的 app 只 需要 读 的 权限 (不 是 写 ), AB 
么 将 需要 声明 READ EXTERNAL STORAGE 权限 。 为 了 确保 app 能 持续 地 正常 工作 ， 
我 们 现在 在 编写 程序 时 就 需要 声明 读 权 限 。 


«manifest ...> 


«uses-permission android:name-"android.permission.READ EXTERNAL STORAGE" /» 
«/manifest» 
但 是 ， 如 果 我 们 的 程序 有 声明 WRITE_EXTERNAL_STORAGE 权限 ， 那 么 就 默认 有 了 
读 的 权限 。 


对 于 internal storage， 我 们 不 需要 声明 任何 权限 ， 因 为 程序 默认 就 有 读 写 程序 目录 下 的 文件 的 
权限 。 


保存 到 Internal Storage 


当 保存 文件 到 internal storage 时 ， 可 以 通过 执行 下 面 两 个 方法 之 一 来 获取 合适 的 目录 作为 
FILE 的 对 象 : 


e getFilesDir() : 返回 一 个 File， 代 表 了 我 们 app 的 internal 目 录 。 

e getCacheDir() : 返回 一 个 File， 代 表 了 我 们 app 的 internal 缓 存 目录 。 请 确保 这 个 目录 下 的 
文件 能 够 在 一 旦 不 再 需要 的 时 候 马 上 被 删除 ， 并 对 其 大 小 进行 合理 限制 ， 例 如 1MB 。 系 
统 的 内 部 存储 空间 不 够 时 ， 会 自行 选择 删除 缓存 文件 。 
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可 以 使 用 File() 构造 器 在 那些 目录 下 创建 一 个 新 的 文件 ， 如 下 : 


File file = new File(context.getFilesDir(), filename); 


同样 ， 也 可 以 执行 openFileOutput() 获取 一 个 FileOutputStream 用 于 写 文 件 到 internal 目 录 。 
如 下 : 


String filename = "myfile"; 
String string - "Hello world!"; 
FileOutputStream outputStream; 


try 1 
outputStream - openFileOutput(filename, Context.MODE PRIVATE); 
outputStream.write(string.getBytes()); 
outputStream.close(); 
) catch (Exception e) { 
e.printStackTrace(); 


} 


如 果 需 要 缓存 一 些 文件 ， 可 以 使 用 createTempFile()。 例 如 : 下 面 的 方法 从 URL 中 抽取 了 一 个 
文件 名 ， 然 后 再 在 程序 的 internal 缓 存 目录 下 创建 了 一 个 以 这 个 文件 名 命名 的 文件 。 


public File getTempFile(Context context, String url) ( 
File file; 
try { 
String fileName - Uri.parse(url).getLastPathSegment(); 
file - File.createTempFile(fileName, null, context.getCacheDir()); 
catch (IOException e) { 
// Error while creating file 


} 


return file; 


Note: 我 们 的 app 的 internal storage 目录 以 app 的 包 名 作为 标识 存放 在 Android 文 件 系统 的 
特定 目录 下 [data/data/com.example.xx]。 从 技术 上 讲 ， 如 果 文 件 被 设置 为 可 读 的 ， 那 么 
其 他 app 就 可 以 读 取 该 internal 文 件 。 然 而 ， 其 他 app 需 要 知道 包 名 与 文件 名 。 若 没有 设置 
为 可 读 或 者 可 写 ， 其 他 app 是 没有 办 法 读 写 的 。 因 此 我 们 只 要 使 用 了 MODE PRIVATE ， 
那么 这 些 文件 就 不 可 能 被 其 他 app 所 访问 。 


保存 文件 到 External Storage 


因为 external storage 可 能 是 不 可 用 的 ， 比 如 遇 到 SD 卡 被 拔 出 等 情况 时 。 因 此 在 访问 之 前 应 对 
其 可 用 性 进行 检查 。 我 们 可 以 通过 执行 getExternalStorageState() 来 查询 external storage 的 
RA 0 FARA AMEDIA MOUNTED, 则 可 以 读 写 。 示 例如 下 : 


/* Checks if external storage is available for read and write */ 
public boolean isExternalStorageWritable() { 
String state - Environment.getExternalStorageState(); 
if (Environment.MEDIA MOUNTED.equals(state)) { 
return true; 


} 


return false; 


/* Checks if external storage is available to at least read */ 
public boolean isExternalStorageReadable() { 
String state = Environment.getExternalStorageState(); 
if (Environment.MEDIA MOUNTED.equals(state) || 
Environment.MEDIA MOUNTED READ ONLY.equals(state)) { 
return true; 


} 


return false; 


K Ž external storage 对 于 用 户 与 其 他 app 是 可 修改 的 ， 我 们 可 能 会 保存 下 面 两 种 类 型 的 文件 。 


e Public files :这 些 文 件 对 与 用 户 与 其 他 app 来 说 是 public 的 ， 当 用 户外 载 我 们 的 app 时 ， 这 
些 文件 应 该 保留 。 例 如 ， 那 些 被 我 们 的 app 拍 摄 的 图 片 或 者 下 载 的 文件 。 

。 Private files: 这 些 文件 完全 被 我 们 的 app 所 私有 ， 它 们 应 该 在 app 被 纯 载 时 删除 。 尽 管 由 
于 存储 在 external storage， 那 些 文件 从 技术 上 而 言 可 以 被 用 户 与 其 他 app 所 访问 ， 但 实际 
上 那些 文件 对 于 其 他 app 没 有 任何 意义 。 因 此 ， 当 用 户 邵 载 我 们 的 app 时 ， 系 统 会 删除 其 
下 的 private 目 录 。 例 如 ， 那 些 被 我 们 的 app 下 载 的 缓存 文件 。 


想 要 将 文件 以 public 形 式 保存 在 external storage 中 ， 请 使 

用 getExternalStoragePublicDirectory() 方 法 来 获取 一 个 File 对 象 ， 该 对 象 表示 存储 在 external 
storage 的 目录 。 这 个 方法 会 需要 带 有 一 个 特定 的 参数 来 指定 这 些 public 的 文件 类 型 ， 以 便于 
与 其 他 public 文 件 进行 分 类 。 参 数 类 型 包括 DIRECTORY _MUSIC 或 者 

DIRECTORY PICTURES. 如 下 : 


public File getAlbumStorageDir(String albumName) { 
// Get the directory for the user's public pictures directory. 
File file - new File(Environment.getExternalStoragePublicDirectory( 
Environment.DIRECTORY PICTURES), albumName); 
if (!file.mkdirs()) { 
Log.e(LOG_TAG, "Directory not created"); 
} 


return file; 


想 要 将 文件 以 private 形 式 保存 在 external storage 中 ， 可 以 通过 执行 getExternalFilesDir() RR 
取 相 应 的 目录 ， 并 且 传 递 一 个 指示 文件 类 型 的 参数 。 每 一 个 以 这 种 方式 创建 的 目录 都 会 被 添 

加 到 external storage 封 装 我 们 app 目 录 下 的 参数 文件 夹 下 (如 下 则 是 albumName) 。 这 下 面 

的 文件 会 在 用 户 印 载 我 们 的 app 时 被 系统 删除 。 如 下 示例 : 


public File getAlbumStorageDir(Context context, String albumName) { 
// Get the directory for the app's private pictures directory. 
File file - new File(context.getExternalFilesDir( 
Environment.DIRECTORY PICTURES), albumName); 
if (!file.mkdirs()) { 
Log.e(LOG_TAG, "Directory not created"); 
} 


return file; 


如 果 刚 开始 的 时 候 ， 没 有 预定 义 的 子 目录 存放 我 们 的 文件 ， 可 以 在 getExternalFilesDir() 方 法 
中 传递 null . 它 会 返回 app 在 external storage 下 的 private 的 根 目 录 。 


请 记 住 ，getExternalFilesDir() 方法 会 创建 的 目录 会 在 app 被 印 载 时 被 系统 删除 。 如 果 我 们 的 
文件 想 在 app 被 删除 时 仍然 保留 ， 请 使 用 getExternalStoragePublicDirectory(). 


无 论 是 使 用 getExternalStoragePublicDirectory() 来 存储 可 以 共享 的 文件 ， 还 是 使 用 
getExternalFilesDir() 来 储存 那些 对 于 我 们 的 app 来 说 是 私有 的 文件 ， 有 一 点 很 重要 ， 那 就 是 
要 使 用 那些 类 似 DIRECTORY_PICTURES 的 API 的 常量 。 那 些 目录 类 型 参数 可 以 确保 那些 文件 被 系 
统 正 确 的 对 待 。 例 如 ， 那 些 以 DIRECTORY_RINGTONES 类 型 保存 的 文件 就 会 被 系统 的 media 
scanner 认 为 是 ringtone 而 不 是 音乐 。 


查询 剩余 空间 


如 果 事 先知 道 想 要 保存 的 文件 大 小 ， 可 以 通过 执行 getFreeSpace() or getTotalSpace() 来 判断 
是 否 有 足够 的 空间 来 保存 文件 ， 从 而 避免 发 生 IDException。 那 些 方法 提供 了 当前 可 用 的 空间 
还 有 存储 系统 的 总 容量 。 


然而 ， 系 统 并 不 能 保证 可 以 写 入 通过 getFreespace() 查询 到 的 容量 文件 ， 人 
量 比 我 们 的 文件 大 小 多 几 MB， 或 者 说 文件 系统 使 用 率 还 不 足 90%， 这 样 则 可 以 继续 进行 写 
操作 ， 否 则 最 好 不 要 写 进去 


的 


Note : 并 没有 强制 要 求 在 写 文 件 之 前 去 检查 剩余 容量 。 我 们 可 以 尝试 先 做 写 的 动作 ， 然 
后 通过 捕获 IOException 。 这 种 做 法 仅 适 合 于 事先 并 不 知道 想 要 写 的 文件 的 确切 大 小 
例如 ， 如 果 在 把 PNG 图 片 转换 成 JPEG 之 前 ， 我 们 并 不 知道 最 终生 成 的 图 片 大 小 是 多 少 。 


删除 文件 


在 不 需要 使 用 某 些 文件 的 时 候 应 删除 它 。 删 除 文件 最 直接 的 方法 是 直接 执行 文件 
的 delete() 方法 。 


myFile.delete(); 


如 果 文 件 是 保存 在 internal storage， 我 们 可 以 通过 context 来 访问 并 通过 执 
行 deleteFile() 进行 删除 


myContext.deleteFile(fileName); 


Note: 2: | P sp &i159applt > android & Z AZARAE LH : 


e 所 有 保存 到 internal storage) X4 ° 
e 所 有 使 用 getExternalFilesDir() 方 式 保存 在 external storage 的 文件 。 


然而 ， 通 常 来 说 ， 我 们 应 该 手动 删除 所 有 通过 getCacheDir() 方式 创建 的 缓存 文件 ， 以 及 


那些 不 会 再 用 到 的 文件 。 


保存 到 数据 库 


编写 :kesenhoo - 原文 :http://developer.android.com/training/basics/data- 
storage/databases.html 


对 于 重复 或 者 结构 化 的 数据 (如 联系 人 信息 ) 等 保存 到 DB 是 个 不 错 的 主意 。 本 课 假 定 读者 已 
经 熟悉 SQL 数据 库 的 常用 操作 。 在 Android 上 可 能 会 使 用 到 的 APIS， 可 以 从 
android.database.sqlite 包 中 找到 。 


定义 Schema 与 Contract 


SQL 中 一 个 重要 的 概念 是 schema : 一 种 DB 结构 的 正式 声明 ， 用 于 表示 database 的 组 成 结 

构 。schema 是 从 创建 DB 的 SQL 语句 中 生成 的 。 我 们 会 发 现 创建 一 个 伴随 类 (companion 
class) 是 很 有 益 的 ， 这 个 类 称 为 合约 类 (contract class) , 它 用 一 种 系统 化 并 且 自 动 生 成 文档 
的 方式 ， 显 示 指 定 了 schema 样 式 。 


Contract Clsss 是 一 些 常量 的 容器 。 它 定义 了 例如 URIs， 表 名 ， 列 名 等 。 这 个 contract 类 允许 
在 同一 个 包 下 与 其 他 类 使 用 同样 的 常量 。 它 让 我 们 只 需要 在 一 个 地 方 修改 列 名 ， 然 后 这 个 列 
名 就 可 以 自动 传递 给 整个 code © 


组 织 contract 类 的 一 个 好 方法 是 在 类 的 根 层 级 定义 一 些 全 局 变量 ， 然 后 为 每 一 个 table 来 创建 内 


Note : 通过 实现 BaseColumns 的 接口 ， 内 部 类 可 以 继承 到 一 个 名 为 _ID 的 主键 ， 这 个 对 
于 Android 里 面 的 一 些 类 似 cursor adaptor 类 是 很 有 必要 的 。 这 么 做 不 是 必须 的 ， 但 这 样 
能 够 使 得 我 们 的 DB 与 Android 的 framework 能 够 很 好 的 相 容 。 


例如 ， 下 面 的 例子 定义 了 表 名 与 该 表 的 列 名 : 


public final class FeedReaderContract { 
// To prevent someone from accidentally instantiating the contract class, 
// give it an empty constructor. 
public FeedReaderContract() {} 


/* Inner class that defines the table contents */ 

public static abstract class FeedEntry implements BaseColumns { 
public static final String TABLE NAME - "entry"; 
public static final String COLUMN NAME ENTRY ID - "entryid"; 
public static final String COLUMN NAME TITLE - "title"; 
public static final String COLUMN NAME SUBTITLE - "subtitle"; 


使 用 SQL Helper 创 建 DB 


定义 好 了 的 DB 的 结构 之 后 ， 就 应 该 实现 那些 创建 与 维护 db 和 table 的 方法 。 下 面 是 一 些 典型 的 
创建 与 删除 table 的 语句 。 


private static final String TEXT TYPE = " TEXT"; 

private static final String COMMA SEP = ","; 

private static final String SQL CREATE ENTRIES - 
"CREATE TABLE " + FeedReaderContract.FeedEntry.TABLE NAME + " (" + 
FeedReaderContract.FeedEntry. ID + " INTEGER PRIMARY KEY," + 
FeedReaderContract.FeedEntry.COLUMN NAME ENTRY ID + TEXT TYPE + COMMA SEP + 
FeedReaderContract.FeedEntry.COLUMN NAME TITLE + TEXT TYPE + COMMA SEP + 

. // Any other options for the CREATE command 


n" Du 


private static final String SQL DELETE ENTRIES - 
"DROP TABLE IF EXISTS ”+ TABLE NAME ENTRIES; 


类 似 于 保存 文件 到 设备 的 internal storage ，Android 会 将 db 保存 到 程序 的 private 的 空间 。 我 们 
的 数据 是 受 保护 的 ， 因 为 那些 区 域 默 认 是 私有 的 ， 不 可 被 其 他 程序 所 访问 。 


在 SQLiteOpenHelper 类 中 有 一 些 很 有 用 的 APls。 当 使 用 这 个 类 来 做 一 些 与 db 有 关 的 操作 时 ， 
系统 会 对 那些 有 可 能 比较 耗 时 的 操作 (例如 创建 与 更 新 等 ) JE GE XS NET ART om 
不 是 在 app 刚 启动 的 时 候 就 去 做 那些 动作 。 我 们 所 需要 做 的 仅仅 是 执行 getWritableDatabase() 
或 者 getReadableDatabase(). 


Note : 因为 那些 操作 可 能 是 很 耗 时 的 ， 请 确保 在 background thread (AsyncTask or 
IntentService) 里 面 去 执行 getWritableDatabase() 或 者 getReadableDatabase() 。 


为 了 使 用 SQLiteOpenHelper, 需要 创建 一 个 子 类 并 重 写 onCreate(), onUpgrade() 5 onOpen() 
等 callback 方 法 。 也 许 还 需要 实现 0nDowngrade(), 但 这 并 不 是 必需 的 。 


例如 ， 下 面 是 一 个 实现 了 SQLiteOpenHelper 类 的 例子 : 


public class FeedReaderDbHelper extends SQLiteOpenHelper { 
// If you change the database schema, you must increment the database version. 
public static final int DATABASE VERSION - 1; 
public static final String DATABASE NAME = "FeedReader.db"; 


public FeedReaderDbHelper(Context context) { 
super(context, DATABASE NAME, null, DATABASE VERSION); 

} 

public void onCreate(SQLiteDatabase db) { 
db.execSQL(SQL CREATE ENTRIES); 


public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { 
// This database is only a cache for online data, so its upgrade policy is 
// to simply to discard the data and start over 
db.execSQL(SQL DELETE ENTRIES); 
onCreate(db); 

} 

public void onDowngrade(SQLiteDatabase db, int oldVersion, int newVersion) { 
onUpgrade(db, oldVersion, newVersion); 


为 了 访问 我 们 的 db， 需 要 实例 化 SQLiteOpenHelper 的 子 类 : 


FeedReaderDbHelper mDbHelper = new FeedReaderDbHelper(getContext()); 


添加 信息 到 DB 
通过 传递 一 个 ContentValues 对 象 到 insert() 方 法 : 


// Gets the data repository in write mode 
SQLiteDatabase db - mDbHelper.getWritableDatabase(); 


// Create a new map of values, where column names are the keys 
ContentValues values - new ContentValues(); 
values.put(FeedReaderContract.FeedEntry.COLUMN NAME ENTRY ID, id); 
values.put(FeedReaderContract.FeedEntry.COLUMN NAME TITLE, title); 
values.put(FeedReaderContract.FeedEntry.COLUMN NAME CONTENT, content); 


// Insert the new row, returning the primary key value of the new row 
long newRowId; 
newRowId - db.insert( 
FeedReaderContract.FeedEntry.TABLE NAME, 
FeedReaderContract.FeedEntry.COLUMN NAME NULLABLE, 
values); 


insert() 方法 的 第 一 个 参数 是 table 名 ， 第 二 个 参数 会 使 得 系统 自动 对 那些 contentvalues 没 
有 提供 数据 的 列 填充 数据 为 null ， 如 果 第 二 个 参数 传递 的 是 null， 那 么 系统 则 不 会 对 那些 没 
有 提供 数据 的 列 进行 填充 。 


从 DB 中 读 取 信息 


为 了 从 DB 中 读 取 数据 ， 需 要 使 用 query() 方 法 ， 传 递 需要 查询 的 条 件 。 查 询 后 
Cursor 对 象 。 


Hp 


返回 一 个 


SQLiteDatabase db = mDbHelper.getReadableDatabase(); 


// Define a projection that specifies which columns from the database 

// you will actually use after this query. 

String[] projection = { 
FeedReaderContract.FeedEntry. ID, 
FeedReaderContract.FeedEntry.COLUMN NAME TITLE, 
FeedReaderContract.FeedEntry.COLUMN NAME UPDATED, 


J; 
// How you want the results sorted in the resulting Cursor 
String sortOrder = 


FeedReaderContract.FeedEntry.COLUMN NAME UPDATED + " DESC"; 


Cursor c = db.query( 
FeedReaderContract.FeedEntry.TABLE NAME, // The table to query 





projection, // The columns to return 

selection, // The columns for the WHERE clause 
selectionArgs, // The values for the WHERE clause 
mule // don't group the rows 

null, // don't filter by row groups 
sortOrder // The sort order 


); 


要 查询 在 cursor 中 的 行 ， 使 用 cursor 的 其 中 一 个 move 方 法 ， 但 必须 在 读 取 值 之 前 调用 。 一 般 

来 说 应 该 先 调 用 moveToFirst() 函数 ， 将 读 取 位 置 置 于 结果 集 最 开始 的 位 置 。 对 每 一 行 ， 我 们 
可 以 使 用 cursor 的 其 中 一 个 get 方 法 如 getstring() 或 getLong() 获取 列 的 值 。 对 于 每 一 个 get 
方法 必须 传递 想 要 获取 的 列 的 索引 位 置 (index position) > 45142: E 7 YA 38 atA 


用 getColumnIndex() 或 getColumnIndexorThrow() 获得 。 


下 面 演示 如 何 从 course 对 象 中 读 取 数 据 信 息 : 


cursor.moveToFirst(); 
long itemId - cursor.getLong( 
cursor.getColumnIndexOrThrow(FeedReaderContract.FeedEntry. ID) 


); 


A s DB 中 的 信息 ON 


和 查询 信息 一 样 ， 删 除数 据 同样 需要 提供 一 些 删除 标准 。DB 的 API 提 供 了 一 个 防止 SQL 注入 
的 机 制 来 创建 查询 与 删除 标准 。 


SQL Injection : ( 随 着 B/S 模式 应 用 开发 的 发 展 ， 使 用 这 种 模式 编写 应 用 程序 的 程序 员 也 
越 来 越 多 。 但 由 于 程序 员 M S 平 及 经 验 也 参差 不 齐 ， 相 当 大 一 部 分 程序 员 在 编写 代码 时 
没有 对 用 户 输 入 数据 的 合法 性 进行 判断 ， 使 应 用 程序 存在 安全 隐患 。 用 户 可 以 提交 一 段 
数据 库 查询 代码 ， Re 返回 的 结果 ， 获 得 某 些 他 想 得 知 的 数据 ， 这 就 是 所 谓 的 SQL 
Injection， 即 SQL 注入 ) 


该 机 制 把 查询 语句 划分 为 选项 条 件 与 选项 参数 两 部 分 。 条 件 定义 了 查询 的 列 的 特征 ， 参 数 用 
于 测试 是 否 符合 前 面 的 条 款 。 由 于 处 理 的 结果 不 同 于 通常 的 SQL 语 句 ， 这 样 可 以 避免 SQL 注 
入 问题 。 


// Define 'where' part of query. 

String selection = FeedReaderContract.FeedEntry.COLUMN NAME ENTRY ID + " LIKE ?"; 
// Specify arguments in placeholder order. 

String[] selelectionArgs = { String.valueOf(rowId) }; 

// Issue SQL statement. 

db.delete(table name, mySelection, selectionArgs); 


更 新 数据 


当 需 要 修改 DB 中 的 某 些 数据 时 ， 使 用 update() 方法 » 


Update 结合 了 插入 与 删除 的 语法 。 


SQLiteDatabase db = mDbHelper.getReadableDatabase(); 


// New value for one column 
ContentValues values - new ContentValues(); 
values.put(FeedReaderContract.FeedEntry.COLUMN NAME TITLE, title); 


// Which row to update, based on the ID 
String selection = FeedReaderContract.FeedEntry.COLUMN NAME ENTRY ID + " LIKE ?"; 
String[] selectionArgs = { String.valueOf(rowId) }; 


int count - db.update( 
FeedReaderDbHelper.FeedEntry.TABLE NAME, 
values, 
selection, 
selectionArgs); 


保存 到 数据 库 


115 


与 其 他 应 用 的 交互 


编写 :kesenhoo - /$ X :http://developer.android.com/training/basics/intents/index.html 


e — Android app 通 常 都 会 有 多 个 activities。 每 个 activity 的 界面 都 扮演 者 用 户 接口 的 角 
色 ， 允 许 用 户 执行 一 些 特定 任务 (例如 查看 地 图 或 者 是 开始 拍照 等 ) 。 为 了 让 用 户 能 够 
从 一 个 activity 跳 到 另 一 个 activity， 我 们 的 app 必 须 使 用 Intent 来 定义 自己 的 意图 。 当 使 用 
startActivity() 的 方法 ， 且 参数 是 intent 时 ， 系 统 会 使 用 这 个 Intent 来 定义 并 启动 合适 的 
app 组 件 。 使 用 intents 甚 至 还 可 以 让 app 局 动 另 一 个 app 里 面 的 activity ° 

e 一 个 Intent 可 以 显 式 的 指明 需要 启动 的 模块 (用 一 个 指定 的 Activity 实 例 ) ， 也 可 以 隐 式 
的 指明 自己 可 以 处 理 哪 种 类 型 的 动作 (比如 拍 一 张 照 等 ) 。 

e 本 章节 将 演示 如 何 使 用 Intent 与 其 他 app 执 行 一 些 基本 的 交互 。 比 如 启动 另外 一 个 app * 
从 其 他 app 接 受 数据 ， 以 及 使 得 我 们 的 app 能 够 响应 从 其 他 app 中 发 出 的 intent 等 。 


Lessons 


e Intent 的 发 送 (Sending the User to Another App ) 
演示 如 何 创建 一 个 隐 式 Intent 唤 起 能 够 接收 这 个 动作 的 App。 

e 接收 Activity 返 回 的 结果 (Getting a Result from an Activity) 
演示 如 何 启 动 另外 一 个 Activity 并 接收 返回 值 。 

e Intent 过 滤 (Allowing Other Apps to Start Your Activity) 


演示 如 何 通过 定义 隐 式 的 Intent 的 过 滤器 来 使 我 们 的 应 用 能 够 被 其 他 应 用 唤起 。 


Intent 的 发 送 


编写 :kesenhoo - 原文 :http://developer.android.com/training/basics/intents/sending.html 


Android 中 最 重要 的 特征 之 一 就 是 可 以 利用 一 个 带 有 action 的 intent 使 当前 app 能 够 跳 转 到 
其 他 app。 例 如 : 如 果 我 们 的 app 有 一 个 地 址 想 要 显示 在 地 图 上 ， 我 们 并 不 需要 在 app 里 面 创 
建 一 个 activity 用 来 显示 地 图 ， 而 是 使 用 Intent 来 发 出 查看 地 址 的 请 求 。Android 系 统 则 会 启动 
能 够 显示 地 图 的 程序 来 呈现 该 地 址 。 


正如 在 1.1 章 节 :建立 你 的 第 一 个 App(Building Your First App) 中 所 说 的 ， 我 们 必须 使 用 intent 来 
在 同一 个 app 的 两 个 activity 之 间 进 行 切 换 。 通 常 是 定义 一 个 显 式 〈explicit) 的 intent， 它 指定 

了 需要 启动 组 件 的 类 名 。 然 而 ， 当 想 要 唤起 不 同 的 app 来 执行 某 个 动作 (比如 查看 地 图 ) ， 则 
we AK ALS A (implicit) 的 intent。 


本 课 会 介绍 如 何 为 特殊 的 动作 创建 一 个 implicit intent， 并 使 用 它 来 启动 另 一 个 app 去 执行 intent 
中 的 action。 


建立 隐 式 的 Intent 


Implicit intents 并 不 声明 要 启动 组 件 的 具体 类 名 ， 而 是 声明 一 个 需要 执行 的 action。 这 个 action 
指定 了 我 们 想 做 的 事情 ， 例 如 查看 ， 编 辑 ， 发 送 或 者 是 获取 一 些 东西 。lntents 通 常会 在 发 送 
action 的 同时 附带 一 些 数据 ， 例 如 你 想 要 查看 的 地 址 或 者 是 你 想 要 发 送 的 邮件 信息 。 数 据 的 具 
体 类 型 取决 于 我 们 想 要 创建 的 Intent， 比 如 Uri 或 其 他 规定 的 数据 类 型 ， 或 者 甚至 也 可 能 根本 不 
需要 数据 。 


如 果 数 据 是 一 个 Uri， 会 有 一 个 简单 的 Intent() constructor 用 于 定义 action 与 data ° 


例如 ， 下 面 是 一 个 带 有 指定 电话 号 码 的 intent。 


Uri number = Uri.parse("tel:5551234"); 
Intent callIntent - new Intent(Intent.ACTION DIAL, number); 


当 app 通 过 执行 startActivity() 启 动 这 个 intent 时 ，Phone app 会 使 用 之 前 的 电话 号 码 来 拨 出 这 个 
电话 。 
下 面 是 一 些 其 他 intent 的 例子 : 


e 查看 地 图 : 


// Map point based on address 

Uri location = Uri.parse("geo:0, 0?q=1600+Amphitheatre+Parkway, +Mountain+View, +Californ 
ia"); 

// Or map point based on latitude/longitude 

// Uri location = Uri.parse("geo:37.422219,-122.08364?z-14"); // z param is zoom level 
Intent mapIntent = new Intent(Intent.ACTION_VIEW, location); 


Uri webpage = Uri.parse("http://www.android.com"); 
Intent webIntent = new Intent(Intent.ACTION_VIEW, webpage); 


至 于 另外 一 些 需要 extra 数据 的 implicit intent， 我 们 可 以 使 用 putExtra() 方法 来 添加 那些 数 
Ho 默认 的 ， 系 统 会 根据 Uri 数 据 类 型 来 决定 需要 哪些 合适 的 MIME type 。 如 果 我 们 没有 在 
intent 中 包含 一 个 Uri, 则 通常 需要 使 用 setType() 方法 来 指定 intent 附 带 的 数据 类 型 。 设 置 
MIME type 是 为 了 指定 应 该 接受 这 个 intent 的 activity。 例 如 : 


e 发 送 一 个 带 附 件 的 email: 


Intent emailIntent = new Intent(Intent.ACTION SEND); 

// The intent does not have a URI, so declare the "text/plain" MIME type 
emailIntent.setType(HTTP.PLAIN TEXT TYPE); 

emailIntent.putExtra(Intent.EXTRA EMAIL, new String[] {"jon@example.com"}); // recipie 
nts 

emailIntent.putExtra(Intent.EXTRA SUBJECT, "Email subject"); 
emailIntent.putExtra(Intent.EXTRA TEXT, "Email message text"); 
emailIntent.putExtra(Intent.EXTRA STREAM, Uri.parse("content://path/to/email/attachmen 
t")); 


// You can also attach multiple items by passing an ArrayList of Uris 


e 创建 一 个 日 历 事件 : 


Intent calendarIntent = new Intent(Intent.ACTION INSERT, Events.CONTENT URI); 

Calendar beginTime - Calendar.getInstance().set(2012, 0, 19, 7, 30); 

Calendar endTime - Calendar.getInstance().set(2012, 0, 19, 10, 30); 
calendarIntent.putExtra(CalendarContract.EXTRA EVENT BEGIN TIME, beginTime.getTimeInMi 
1lis()); 

calendarIntent.putExtra(CalendarContract.EXTRA EVENT END TIME, endTime.getTimeInMillis 
0); 

calendarIntent.putExtra(Events.TITLE, "Ninja class"); 
calendarIntent.putExtra(Events.EVENT LOCATION, "Secret dojo"); 


Note: 这 个 intent for Calendar 的 例子 只 使 用 于 >=API Level 14 ° 


Note: 请 尽 可 能 的 将 Intent 定 义 的 更 加 确切 。 例 如 ， 如 果 想 要 使 用 ACTION_VIEW 的 
intent 来 显示 一 张 图 片 ， 则 还 应 该 指定 MIME type 为 image/* .这 样 能 够 阻止 其 他 能 够 "A 
看 " 其 他 数据 类 型 的 app (比如 一 个 地 图 app) 被 这 个 intent 叫 起 。 


验证 是 否 有 App 去 接收 这 个 Intent 


尽管 Android 系 统 会 确保 每 一 个 确定 的 intent 会 被 系统 内 置 的 app(such as the Phone, Email, or 
Calendar app) 之 一 接收 ， 但 是 我 们 还 是 应 该 在 触发 一 个 intent 之 前 做 验证 是 否 有 App 接 受 这 个 
intent 的 步骤 。 


Caution: 如 果 触 发 了 一 个 intent， 而 且 没 有 任何 一 个 app 会 去 接收 这 个 intent ， 则 app 会 
crash ° 


为 了 验证 是 否 有 合适 的 activity 会 响应 这 ST ， 需 要 执行 querylntentActivities() 来 获取 到 能 
够 接收 这 个 intent 的 所 有 activity 的 list。 若 返回 的 List 非 空 ， 那 么 我 们 才 可 以 安全 的 使 用 这 个 
intent。 例 如 : 


PackageManager packageManager = getPackageManager(); 
List«ResolveInfo» activities = packageManager.queryIntentActivities(intent, 0); 
boolean isIntentSafe = activities.size() > 0; 


如 果 isIntentsafe A true ,那么 至 少 有 一 个 app 可 以 响应 这 个 intent。 false 则 说 明 没有 app 
可 以 handle 这 个 intent 。 


Note: 我 们 必须 在 第 一 次 使 用 之 前 做 这 个 检查 ， 若 是 不 可 行 ， 则 应 该 关闭 这 个 功能 。 如 果 
知道 某 个 确切 的 app 能 够 handle 这 个 intent， 我 们 也 可 以 向 用 户 提 供 下 载 该 app 的 链接 。 
(see how to link to your product on Google Play). 


1& F| Intent è = Activity 


当 创 建 好 了 intent 并 且 设 置 好 了 extra 数 据 后 ， 通 过 执行 startActivity() 将 intent 发 送 到 系统 。 若 
系统 确定 了 多 个 activity 可 以 handle 这 个 intent, 它 会 显示 出 一 个 dialog， 让 用 户 选择 尼 动 哪个 
app。 如 果 系统 发 现 只 有 一 个 app 可 以 handle 这 个 intent， 则 系统 将 直接 启动 该 app。 


startActivity(intent); 


Browser 


o Nie 


Use by default for this action 





下 面 是 一 个 演示 了 如 何 创 建 一 个 intent 来 查看 地 图 的 完整 例子 ， 首 先 验证 有 app 可 以 handle 这 
个 intent, 然 后 启动 它 。 


// Build the intent 

Uri location = Uri.parse("geo:0, 0?q=1600+Amphitheatre+Parkway, +Mountain+View, +Californ 
ia"); 

Intent mapIntent = new Intent(Intent.ACTION_VIEW, location); 


// Nerify it resolves 

PackageManager packageManager = getPackageManager (); 

List«ResolveInfo» activities = packageManager.queryIntentActivities(mapIntent, 0); 
boolean isIntentSafe = activities.size() > 0; 


// Start an activity if it's safe 
if (isIntentSafe) { 
startActivity(mapIntent); 


显示 分 至 App 的 选择 界面 


请 注意 ， 当 以 startActivity() 的 形式 传递 一 个 intent， 并 且 有 多 个 app 可 以 handle 时 ， 用 户 可 以 在 
弹出 dialog 的 时 候选 择 默认 启动 的 app (通过 色 选 dialog 下 面 的 选择 框 ， 如 上 图 所 示 ) 。 该 功 
o m 有 用 〈 例 如 用 户 总 是 喜欢 启动 某 个 app 来 查看 网 页 ， 总 是 喜 
启动 某 个 camera 来 拍照 ) 。 


然而 ， 如 果 用 户 布 望 每 次 都 弹出 选择 界面 ， 欠 都 不 确定 会 选择 哪个 app 启 动 ， 例 如 分 享 
功能 ， 用 户 选 择 分 享 到 哪个 app 都 是 不 确定 的 ， ee: 择 的 对 话 框 。 (这 
种 情况 下 用 户 不 能 选择 默认 启动 的 app) 。 


Bluetooth 


Gmail 


Google Voice 


Google* 


Messaging 


Twitter 





为 了 显示 chooser, 需要 使 用 createChooser() 来 创建 Intent 


Intent intent = new Intent(Intent.ACTION SEND); 


// Always use string resources for UI text. This says something like "Share this photo 
with" 

String title - getResources().getText(R.string.chooser title); 

// Create and start the chooser 

Intent chooser - Intent.createChooser(intent, title); 

startActivity(chooser); 


这 样 就 列 出 了 可 以 响应 createchooser() 中 Intent 的 app， 并 且 指 定 了 标题 。 


接收 Activity 返 回 的 结果 


编写 :kesenhoo - Æ X:http://developer.android.com/training/basics/intents/result.html 


启动 另外 一 个 activity 并 不 一 定 是 单 向 的 。 我 们 也 可 以 启动 另外 一 个 activity 然 后 接受 一 个 返回 
的 result。 为 接受 result， 我 们 需要 使 用 startActivityForResult() ， 而 不 是 startActivity() 。 


例如 ， 我 们 的 app 可 以 启动 一 个 camera 程 序 并 接受 拍 的 照片 作为 result。 或 者 可 以 启动 联系 人 
程序 并 获取 其 中 联系 的 人 的 详情 作为 result 。 


当然 ， 被 启动 的 activity 需 要 指定 返回 的 result。 它 需要 把 这 个 result 作 为 另外 一 个 intent 对 象 返 
回 ， 我 们 的 activity 需 要 在 onActivityResult() 的 回调 方法 里 面 去 接收 result 。 


Note: 在 执行 startActivityForResult() 时 ， 可 以 使 用 explicit 或 者 implicit 的 intent。 当 局 
动 另 外 一 个 位 于 的 程序 中 的 activity 时 ， 我 们 应 该 使 用 explicit intent 来 确保 可 以 接收 到 期 
待 的 结果 。 


有 局 动 Activity 


对 于 startActivityForResult() 方法 中 的 intent 与 之 前 介绍 的 并 无 太 大 差异 ， 不 过 是 需要 在 这 个 方 
法 里 面 多 添加 一 个 int 类 型 的 参数 。 


该 integer 参 数 称 为 "request code"， 用 于 标识 请 求 。 当 我 们 接收 到 result Intent 时 ， 可 从 回调 方 
法 里 面 的 参数 去 判断 这 个 result 是 否 是 我 们 想 要 的 。 


例如 ， 下 面 是 一 个 局 动 activity 来 选择 联系 人 的 例子 


static final int PICK CONTACT REQUEST = 1; // The request code 


private void pickContact() { 

Intent pickContactIntent = new Intent(Intent.ACTION PICK, Uri.parse("content://con 
tacts) 

pickContactIntent.setType(Phone.CONTENT TYPE); // Show user only contacts w/ phone 
numbers 

startActivityForResult(pickContactIntent, PICK CONTACT REQUEST); 


接收 Result 


当 用 户 完成 了 启动 之 后 activity 操 作 之 后 ， 系 统 会 调用 我 们 activity 中 的 onActivityResult() 回调 
方法 。 该 方法 有 三 个 参数 : 


e 通过 startActivityForResult() 传 递 的 request code ° 

e 第 二 个 activity 指 定 的 result code。 如 果 操 作成 功 则 是 REsULT OK ， 如 果 用 户 没有 操作 成 
功 ， 而 是 直接 点 击 回 退 或 者 其 他 什么 原因 ， 那 么 则 是 RESULT. CANCELED 

e 包含 了 所 返回 result 数 据 的 intent。 


例如 ， 下 面 显示 了 如 何 处 理 pick a contact 的 result : 


@Override 
protected void onActivityResult(int requestCode, int resultCode, Intent data) { 
// Check which request we're responding to 
if (requestCode == PICK_CONTACT_REQUEST) { 
// Make sure the request was successful 
if (resultCode == RESULT_OK) { 
// The user picked a contact. 
// The Intent's data Uri identifies which contact was selected. 


// Do something with the contact here (bigger example below) 


本 例 中 被 返回 的 Intent 使 用 Uri 的 形式 来 表示 返回 的 联系 人 。 


为 正确 处 理 这 些 result， 我 们 必须 了 解 那些 result intent 的 格式 。 对 于 自己 程序 里 面 的 返回 
result 是 比较 简单 的 。Apps 都 会 有 一 些 自己 的 api 来 指定 特定 的 数据 。 例 如 ，People app 
(Contacts app on some older versions) 总 是 返回 一 个 URI 来 指定 选择 的 contact，Camera app 
则 是 在 data 数据 区 返回 一 个 Bitmap (see the class about Capturing Photos). 


读 取 联 系 人 数据 


上 面 的 代码 展示 了 如 何 获 取 联 系 人 的 返回 结果 ， 但 没有 说 清楚 如 何 从 结果 中 读 取 数据 ， 因 为 
这 需要 更 多 关于 content providers 的 知识 。 但 如 果 想 知道 的 话 ， 下 面 是 一 段 代 码 ， 展 示 如 何 从 
被 选 的 联系 人 中 读 出 电话 号 码 。 


接收 Activity 返 回 的 结果 


@Override 
protected void onActivityResult(int requestCode, int resultCode, Intent data) { 
// Check which request it is that we're responding to 
if (requestCode == PICK_CONTACT_REQUEST) { 
// Make sure the request was successful 
if (resultCode == RESULT_OK) { 
// Get the URI that points to the selected contact 
Uri contactUri = data.getData(); 
// We only need the NUMBER column, because there will be only one row in t 
he result 
String[] projection = {Phone.NUMBER}; 


// Perform the query on the contact to get the NUMBER column 

// We don't need a selection or sort order (there's only one result for th 
e given URI) 

// CAUTION: The query() method should be called from a separate thread to 
avoid blocking 

// your app's UI thread. (For simplicity of the sample, this code doesn't 


do that.) 
// Consider using CursorLoader to perform the query. 
Cursor cursor - getContentResolver() 

.query(contactUri, projection, null, null, null); 
cursor.moveToFirst(); 
// Retrieve the phone number from the NUMBER column 
int column = cursor.getColumnIndex(Phone.NUMBER); 
String number = cursor.getString(column); 
// Do something with the phone number... 
} 
} 
} 


Note: 在 Android 2.3 (API level 9) 之 前 对 contacts Provider 的 请 求 (比如 上 面 的 代码 )， 需 
要 声明 READ_CONTACTS 权限 (更 多 详 见 Security and Permissions)。 但 如 果 是 Android 2.3 以 
上 的 系统 就 不 需要 这 么 做 。 但 这 种 临时 权限 也 仅 限 于 特定 的 请 求 ， 所 以 仍 无 法 获取 除 返 
回 的 Intent 以 外 的 联系 人 人 信息， 除非 声明 了 READ_CONTACTS 权限 。 
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^h 5 :Kesenhoo - /$ X :http://developer.android.com/training/basics/intents/filters.html 


前 两 节 课 主要 讲 了 从 一 个 app 启 动 另 外 一 个 app。 但 如 果 我 们 的 app 的 功能 对 别 的 app 也 有 用 ， 
那么 其 应 该 做 好 响应 的 准备 。 例 如 ， 如 果 创 建 了 一 个 social app， 它 可 以 分 享 messages 或 者 
photos 给 好 友 ， 那 么 最 好 我 们 的 app 能 够 接收 AcTION_SEND 的 intent, 这 样 当 用 户 在 其 他 app 触 
发 分 享 功能 的 时 候 ， 我 们 的 app 能 够 出 现在 待 选 对 话 框 。 


通过 在 manifest 文 件 中 的 <activity> 标签 下 添加 <intent-filter> 的 属性 ， 使 其 他 的 app 能 够 
启动 我 们 的 activity 。 

当 app 被 安装 到 设备 上 时 ， 系 统 可 以 识别 intent filter 并 把 这 些 信息 记录 下 来 。 当 其 他 app 使 用 
implicit intent 执 行 startActivity() 或 者 startActivityForResult() 时 ， 系 统 会 自动 查找 出 那些 可 以 
响应 该 intent 的 activity ° 


添加 Intent Filter 


为 了 尽 可 能 确切 的 定义 activity 能 够 handle 的 intent， 每 一 个 intent filter 都 应 该 尽 可 能 详尽 的 定 
义 好 action 与 data。 


若 activity 中 的 intent filter 满 足以 下 intent 对 象 的 标准 ， 系 统 就 能 够 把 特定 的 intent 发 送 给 
activity : 


e Action: 一 个 想 要 执行 的 动作 的 名 称 。 通 常 是 系统 已 经 定义 好 的 值 ， 
如 ACTION SEND 3X ACTION VIEW ° 在 intent filter 中 通过 <action> 指定 它 的 值 ， 值 的 类 型 
必须 为 字符 串 ， 而 不 是 API 中 的 常量 (看 下 面 的 例子 ) 


e Data:Intent 附 带 数 据 的 描述 。 在 intent filter 中 通过 <data> 指定 它 的 值 ， 可 以 使 用 一 个 或 
者 多 个 属性 ， 我 们 可 以 只 定义 MIME type 或 者 是 只 指定 URI prefix， 也 可 以 只 定义 一 个 
URI scheme， 或 者 是 他 们 综合 使 用 。 


Note: 如 果 不 想 handle Uri 类 型 的 数据 ， 那 么 应 该 指定 android:mimeType 属性 。 例 如 


text/plain or image/jpeg. 


e Category: 提 供 一 个 附加 的 方法 来 标识 这 个 activity 能 够 handle 的 intent。 通 常 与 用 户 的 手 
势 或 者 是 启动 位 置 有 关 。 系 统 有 支持 几 种 不 同 的 categories, 但 是 大 多 数 都 很 少 用 到 。 而 
且 ， 所 有 的 implicit intents 都 默认 是 CATEGORY. DEFAULT 类 型 的 。 在 intent filter 中 
用 <Category> 指定 它 的 值 


在 我 们 的 intentfilter 中 ， 可 以 在 <intent-filter> 元 素 中 定义 对 应 的 XML 元 素来 声明 我 们 的 
activity 使 用 何 种 标准 。 


例如 ， 这 个 有 intentfilter 的 activity， 当 数据 类 型 为 文本 或 图 像 时 会 处 理 AcTION sEND 的 
intent ° 


«activity android:name="ShareActivity"> 
<intent-filter> 
<action android:name="android.intent.action.SEND"/> 
<category android:name="android.intent.category.DEFAULT"/> 
<data android:mimeType="text/plain"/> 
<data android:mimeType="image/*"/> 
</intent-filter> 


</activity> 


每 一 个 发 送出 来 的 intent 只 会 包含 一 个 action 与 data 类 型 ， 但 handle 这 个 intent 的 activity 的 


<intent-filter> 可 以 声明 多 个 <action> ，<category> 与 <data> 。 


如 果 任 何 的 两 对 action 与 data 是 互相 矛盾 的 ， 就 应 该 创建 不 同 的 intent filter 来 指定 特定 的 action 
与 type ° 


例如 ， 假 设 我 们 的 activity 可 以 handle 文本 与 图 片 ， 无 论 是 ACTION_SEND 还 是 ACTION SENDTO 
的 intent。 在 这 种 情况 下 ， 就 必须 为 两 个 action 定 义 两 个 不 同 的 intent filter » 
为 ACTION_SENDTO intent 必须 使 用 Uri 类 型 来 指定 接收 者 使 用 send 或 sendto 的 地 址 。 例 如 : 


«activity android:name="ShareActivity"> 
<!-- filter for sending text; accepts SENDTO action with sms URI schemes --> 
<intent-filter> 
<action android:name="android.intent.action.SENDTO"/> 
«category android:name-"android.intent.category.DEFAULT"/» 
«data android:scheme="sms" /> 
«data android:scheme="smsto" /> 
</intent-filter> 


<!-- filter for sending text or images; accepts SEND action and text or image data 
eS 


«intent-filter- 
«action android:name-"android.intent.action.SEND"/» 
«category android:name-"android.intent.category.DEFAULT"/» 
«data android:mimeType="image/*"/> 
«data android:mimeType="text/plain"/> 
</intent-filter> 
</activity> 


Note:4 1 4 Zimplicit intents, 必须 在 我 们 的 intent filter? @& 4 CATEGORY DEFAULT 
的 category 。startActivity() 和 startActivityForResult() 方 法 将 所 有 intent 视 为 声明 了 
CATEGORY DEFAULT category。 如 果 没 有 在 的 intent filter 中 声明 

CATEGORY _DEFAULT，activity 将 无 法 对 implicit intent 做 出 响应 。 


更 多 sending 与 receiving ACTION SEND intents 执 行 social sharing 行 为 的 ， 请 查看 上 一 课 : 
接收 Activity 返 回 的 结果 (Getting a Result from an Activity) 


NO 


在 Activity 中 Handle 发 送 过 来 的 Intent 


为 了 决定 采用 哪个 action， 我 们 可 以 读 取 |ntent 的 内 容 。 


可 以 raeng 来 获取 启动 我 们 activity 的 那个 intent。 我 们 可 以 在 activity 生 命 周 期 的 任何 
时 候 去 执行 这 个 方法 ， 但 最 好 是 在 oncreate() 或 者 onstart() 里 面 去 执行 。 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


setContentView(R.layout.main); 


// Get the intent that started this activity 
Intent intent - getIntent(); 
Uri data = intent.getData(); 


// Figure out what to do based on the intent type 
if (intent.getType().indexOf("image/") != -1) { 

// Handle intents with image data ... 
} else if (intent.getType().equals("text/plain")) { 





// Handle intents with text ... 


返回 Result 


如 果 想 返回 一 个 result 给 启动 的 那个 activity， 仅 仅 需要 执行 SetResult()， 通 过 指定 一 个 result 
code 与 result intent。 操 作 完 成 之 后 ， 用 户 需 要 返回 到 原来 的 activity， 通 过 执行 finish() 关闭 被 
唤起 的 activity ° 


// Create intent to deliver some kind of result data 
Intent result - new Intent("com.example.RESULT ACTION", Uri.parse("content://result ur 
TE 
setResult(Activity.RESULT OK, result); 
finish(); 


我 们 必须 总 是 指定 一 个 result code ° 38 3$ Are REsULT OK 就 是 RESULT_CANCELED 。 我 们 可 以 通 
过 Intent 来 添加 需要 返回 的 数据 。 


Note: 上 默认 的 result code RESULT_CANCELED .因此 ， 如 果 用 户 在 没有 完成 操作 之 前 点 


ALI 


back key， 那 么 之 前 的 activity 接 受到 | 的 result code 就 是 "canceled"。 


如 果 只 是 纯粹 想 要 返回 一 个 int 来 表示 某 些 返回 的 result 数 据 之 一 ， 则 可 以 设置 result code 为 任 
何 大 于 0 的 数值 。 如 果 我 们 返回 的 result 只 是 一 个 int， 那 么 连 intent 都 可 以 不 需要 返回 了 ， 可 以 
调用 setResult() 然后 只 传递 result code 如 下 : 


setResult (RESULT_COLOR_RED) ; 
finish(); 


Note: 我 们 没有 必要 在 意 自己 的 activity 是 被 用 startActivity() 还 是 startActivityForResult() 


方法 所 叫 起 的 。 系 统 会 自动 去 判断 该 如 何 传递 result。 在 不 需要 的 result 的 case F > result 
会 被 自动 忽略 。 


Android 分 享 操作 (Building Apps with 
Content Sharing) 


编写 :kesenhoo - 原文 :http://developer.android.com/training/building-content- 
sharing.html 


这 一 系列 课程 会 教 你 如 何 创建 可 以 在 不 同 的 应 用 与 设备 之 间 进 行 分 享 的 应 用 。 
分 享 简单 的 数据 (Sharing Simple Data) 


学 习 如 何 使 得 你 的 应 用 可 以 和 其 他 应 用 进行 交互 。 分 享 信息 ， 接 收 信息 ， 为 用 户 数据 提供 一 
个 简单 并 且 可 扩展 的 方式 来 执行 分 享 操作 。 


分 享 文件 (Sharing Files) 


学 习 使 用 一 个 URI 与 临时 的 访问 权限 来 提供 安全 的 文件 访问 。 


使 用 NFC 分 享 文件 (Sharing Files with NFC) 


学 习 使 用 NFC 功 能 实现 设备 间 的 文件 传递 。 


Im F&F * à 米 
分 至 简单 的 数据 
编写 :kesenhoo - 原文 :http://developer.android.com/training/sharing/index.html 


程序 间 可 以 互相 通信 是 Android 程 序 中 最 棒 的 功能 之 一 。 当 一 个 功能 已 存在 于 其 他 app 中 ， 且 
并 不 是 本 程序 的 核心 功能 时 ， 完 全 没有 必要 重新 对 其 进行 编写 。 


本 章节 会 讲述 一 些 通 在 不 同 程序 之 间 通 过 使 用 Intent APls 与 ActionProvider 对 象 来 发 送 与 接受 
content 的 常用 方法 。 


Lessons 


e 向 其 他 App 发 送 简单 的 数据 - Sending Simple Data to Other Apps 
学 习 如 何 使 用 intent 向 其 他 app 发 送 text 与 binary 数 据 。 
e 接收 从 其 他 App 返 回 的 数据 -Receiving Simple Data from Other Apps 
学 习 如 何 通过 Intent 在 我 们 的 app 中 接收 来 自 其 他 app 的 text 与 binary 数 据 。 
。 给 ActionBar 增 加 分 享 功能 - Adding an Easy Share Action 


学 习 如 何在 Acitonbar 上 添加 一 个 分 享 功 能 。 


其 他 App 发 送 简单 的 数据 


编写 :kesenhoo - 原文 :http://developer.android.com/training/sharing/send.html 


在 构建 一 个 intent 时 ， 必 须 指 定 这 个 intent 需 要 触发 的 actions 。Android 定 义 了 一 些 actions， 上 比 
如 ACTION_SEND， 该 action 表 明 该 intent 用 于 从 一 个 activity 发 送 数据 到 另外 一 个 activity 的 ， 
其 至 可 以 是 跨 进程 之 间 的 数据 发 送 。 


A 
够 兼容 接受 的 这 些 数据 的 activity。 如 果 这 些 选择 有 多 个 ， 则 把 这 些 activity 显 示 给 用 户 进行 选 
择 ; 如 果 只 有 一 个 ， 则 立即 局 a Ad 。 同样 的 ， 我 们 可 以 在 manifest 文 件 的 Activity 描 述 
中 添加 接受 的 数据 类 型 。 


为 了 发 送 数据 到 另外 一 个 activity， 我 们 只 、 定数 据 与 数据 的 类 型 ， 系 统 会 自动 识别 出 能 
Ul 


在 不 同 的 程序 之 问 使 用 intent 收 发 数据 是 在 社交 分 享 内 容 时 最 常用 的 方法 。Intent 使 用 户 能 够 
通过 最 常用 的 程序 进行 快速 简单 的 分 享 信 息 。 


注意 :为 ActionBar 添 加 分 享 功 能 的 最 佳 方法 是 使 用 ShareActionProvider， 其 运行 与 APllevel 
14 以 上 的 系统 。ShareActionProvider 将 在 第 3 课 中 进行 详细 介绍 。 


分 享 文本 内 容 (Send Text Content) 


ACTION_SEND 最 直接 常用 的 地 方 是 从 一 个 Activity 发 送 文本 内 容 到 另外 一 个 Activity 。 d , 
Android 内 置 的 浏览 器 可 以 将 当前 显示 页 面 的 URL 作 为 文本 内 容 分 享 到 其 他 程序 。 这 一 功能 

于 通过 邮件 或 者 社交 网 络 来 分 享 文章 或 者 网 址 给 好 友 而 言 是 非常 有 用 的 。 ion AS 
Code: 


Intent sendIntent - new Intent(); 
sendIntent.setAction(Intent.ACTION SEND); 
sendIntent.putExtra(Intent.EXTRA TEXT, "This is my text to send."); 
sendIntent.setType(" text/plain"); 

startActivity(sendIntent); 


如 果 设 备 上 安装 有 某 个 能 够 匹配 ACTION_SEND 了 且 MIME 类 型 为 text/plain 的 程序 ， 则 Android 
系统 会 立即 执行 它 。 若 有 多 个 匹配 的 程序 ， 则 系统 会 把 他 们 都 给 筛选 出 来 ， 并 呈现 Dialog 给 用 
户 进行 选择 。 

如 果 为 intent 调 用 了 Intent.createChooser()， 那 么 Android 总 是 会 显示 可 供 选 择 。 这 样 有 一 些 好 
Ab: 


e 即使 用 户 之 前 为 这 个 intent 设 置 了 默认 的 action， 选 择 界面 还 是 会 被 显示 。 
e. 如 果 没有 匹配 的 程序 ? Android 会 显示 系统 信息 m ° 


e 我 们 可 以 指定 选择 界面 的 标题 。 


下 面 是 更 新 后 的 代码 : 


Intent sendIntent = new Intent(); 

sendIntent.setAction(Intent.ACTION SEND); 

sendIntent.putExtra(Intent.EXTRA TEXT, "This is my text to send."); 
sendIntent.setType("text/plain"); 

startActivity(Intent.createChooser(sendIntent, getResources().getText(R.string.send to 


)); 


效果 图 如 下 : 


Bluetooth 
Gmail 


Google* 


Messaging 


Share via barcode 


Twitter 





另外 ,我 们 可 以 为 intent 设 置 一 些 标准 的 附加 值 ， 例 如 : EXTRA. EMAIL, EXTRA CC, 
EXTRA_BCC, EXTRA_SUBJECT 等 。 然 而 ， 如 果 接 收 程序 没有 针对 那些 做 特殊 的 处 理 ， 则 
不 会 有 对 应 的 反应 。 


注意 :一 些 e-mail 程 序 ， 例 如 Gmail, 对 应 接收 的 是 EXTRA_EMAIL 与 EXTRA_CC， 他 们 都 是 
String & #! &j > "T Rž A putExtra(string,string[]) > 2& ok 7& Ae Zintent F » 


4 3X = it 4l A € (Send Binary Content) 


分 享 二 进 制 的 数据 需要 结合 设置 特定 的 MIME 类 型 ,需要 在 EXTRA STREAM € dk BREN 
URI, 下 面 有 个 分 享 图 片 的 例子 ， 该 例子 也 可 以 修改 用 于 分 享 任何 类 型 的 二 进 制 数据 : 


Intent ShareIntent = new Intent(); 

sharelIntent.setAction(Intent.ACTION SEND); 

sharelIntent.putExtra(Intent.EXTRA STREAM, uriToImage); 

shareIntent.setType(" image/jpeg"); 

startActivity(Intent.createChooser(shareIntent, getResources().getText(R.string.send t 


0))); 


请 注意 以 下 内 容 : 


e 我 们 可 以 使 用 */* 这 样 的 方式 来 指定 MIME 类 型 ， 但 是 这 仅仅 会 match 到 那些 能 够 处 理 一 
般 数 据 类 型 的 Activity( 即 一 般 的 Activity 无 法 详尽 所 有 的 MIME 类 型 ) 
e 接收 的 程序 需要 有 访问 URI 资 源 的 权限 。 下 面 有 一 些 方法 来 处 理 这 个 问题 : 
o 将 数据 存储 在 ContentProvider 中 ， 确 保 其 他 程序 有 访问 provider 的 权限 。 较 好 的 提供 
访问 权限 的 方法 是 使 用 per-URI permissions， 其 对 接收 程序 而 言 是 只 是 暂时 拥有 该 
许可 权限 。 类 似 于 这 样 创建 ContentProvider 的 一 种 简单 的 方法 是 使 用 FileProvider 
helper 类 。 
o 使 用 MediaStore 系 统 。MediaStore 系 统 主 要 用 于 音 视频 及 图 片 的 MIME 类 型 。 但 在 
Android3.0 之 后 ， 其 也 可 以 用 于 存储 非 多 媒体 类 型 。 


发 送 多 块 内 容 (Send Multiple Pieces of Content) 


为 了 同时 分 享 多 种 不 同类 型 的 内 容 ， 需 要 使 用 ACTION_SEND_MULTIPLE 与 指定 到 那些 数据 的 
URIs 列 表 。MIME 类 型 会 根据 分 享 的 混合 内 容 而 不 同 。 例 如 ， 如 果 分 享 3 张 JPEG 的 图 片 ， 那 
么 MIME 类 型 仍然 是 image/jpeg 。 如 果 是 不 同 图 片 格式 的 话 ， 应 该 是 用 image/* 来 匹配 那些 
可 以 接收 任何 图 片 类 型 的 activity。 如 果 需 要 分 享 多 种 不 同类 型 的 数据 ， 可 以 使 用 */* 来 表示 
MIME。 像 前 面 描述 的 那样 ， 这 取决 于 那些 接收 的 程序 解析 并 处 理 我 们 的 数据 。 下 面 是 一 个 例 
f 


ArrayList«Uri» imageUris = new ArrayList<Uri>(); 
imageUris.add(imageUri1); // Add your image URIs here 
imageUris.add(imageUri2); 


Intent shareIntent = new Intent(); 
shareIntent.setAction(Intent.ACTION SEND MULTIPLE); 
sharelIntent.putParcelableArrayListExtra(Intent.EXTRA STREAM, imageUris); 
shareIntent.setType("image/*"); 
startActivity(Intent.createChooser(shareIntent, "Share images to..")); 


当然 ， 请 确保 指定 到 数据 的 URIs 能 够 被 接收 程序 所 访问 (添加 访问 权限 ) 。 


接收 从 其 他 App 传 送 来 的 数据 


编写 :kesenhoo - 原文 :http://developer.android.com/training/sharing/receive.html 


就 像 我 们 的 程序 能 够 分 享 数据 给 其 他 程序 一 样 ， 其 也 能 方便 的 接收 来 自 其 他 程序 的 数据 。 需 
要 考虑 的 是 用 户 与 我 们 的 程序 如 何 进行 交互 ， 以 及 我 们 想 要 从 其 他 程序 接收 数据 的 类 型 。 例 
如 ， 一 个 社交 网 络 程序 可 能 会 希望 能 够 从 其 他 程序 接受 文本 数据 ， 比 如 一 个 有 趣 的 网 址 链 
接 。Google+ 的 Android 客 户 端 会 接受 文本 数据 与 单 张 或 者 多 张 图 片 。 用 户 可 以 简单 的 从 
Gallery 程 序 选 择 一 张 图 片 来 启动 Google+， 并 利用 其 发 布 文本 或 图 片 。 


更 新 我 们 的 manifest 文 件 (Update Your Manifest) 


Intent filters 告 诉 Android 系 统一 个 程序 愿意 接受 的 数据 类 型 。 类 似 于 上 一 课 ， 我 们 可 以 创建 
intent filters 来 表明 程序 能 够 接收 的 action 类 型 。 下 面 是 个 例子 ， 对 三 个 activit 分 别 指定 接受 单 
张 图 片 ， 文 本 与 多 张 图 片 。(Intent filter 相 关 资 料 ， 请 参考 Intents and Intent Filters) 


«activity android:name=".ui.MyActivity" > 

<intent-filter> 
<action android:name="android.intent.action.SEND" /> 
«category android: name="android.intent.category.DEFAULT" /> 
«data android:mimeType="image/*" /> 

</intent-filter> 

<intent-filter> 
<action android:name="android.intent.action.SEND" /> 
<category android:name="android.intent.category.DEFAULT" /> 
<data android:mimeType="text/plain" /> 

</intent-filter> 

<intent-filter> 
«action android:name-"android.intent.action.SEND MULTIPLE" /> 
<category android:name="android.intent.category.DEFAULT" /> 
<data android:mimeType="image/*" /> 

</intent-filter> 


</activity> 
当 某 个 程序 尝试 通过 创建 一 个 intent 并 将 其 传递 给 startActivity 来 分 享 一 些 东 西 时 ， 我 们 的 程序 


会 被 呈现 在 一 个 列表 中 让 用 户 进行 选择 。 如 果 用 户 选择 了 我 们 的 程序 ， 相 应 的 activity 会 被 调 
用 开启 ， 这 个 时 候 就 是 我 们 如 何 处 理 获取 到 的 数据 的 问题 了 。 


处 理 接受 到 的 数据 (Handle the Incoming Content) 


为 了 处 理 从 Intent 带 来 的 数据 ， 可 以 通过 调用 getlntent() 方 法 来 获取 到 Intent 对 象 。 拿 到 这 个 对 
象 后 ， 我 们 可 以 对 其 中 面 的 数据 进行 判断 ， 从 而 决定 下 一 步行 为 。 请 记 住 ， 如 果 一 个 activity 
可 以 被 其 他 的 程序 启动 ， 我 们 需要 在 检查 intent 的 时 候 考 虑 这 种 情况 (是 被 其 他 程序 而 调用 启动 
的 ) 。 


void onCreate (Bundle savedInstanceState) { 


// Get intent, action and MIME type 
Intent intent - getIntent(); 

String action - intent.getAction(); 
String type - intent.getType(); 


if (Intent.ACTION SEND.equals(action) && type !- null) ( 
if ("text/plain".equals(type)) { 
handleSendText(intent); // Handle text being sent 
) else if (type.startswith("image/")) { 
handleSendImage(intent); // Handle single image being sent 


) else if (Intent.ACTION SEND MULTIPLE.equals(action) && type != null) { 
if (type.startsWith("image/")) { 
handleSendMultipleImages(intent); // Handle multiple images being sent 


} else { 
// Handle other intents, such as being started from the home screen 


void handleSendText(Intent intent) { 
String sharedText = intent.getStringExtra(Intent.EXTRA TEXT); 
if (sharedText != null) { 
// Update UI to reflect text being shared 


void handleSendImage(Intent intent) { 
Uri imageUri - (Uri) intent.getParcelableExtra(Intent.EXTRA STREAM); 
if (imageUri != null) { 
// Update UI to reflect image being shared 


void handleSendMultipleImages(Intent intent) { 
ArrayList«Uri» imageUris - intent.getParcelableArrayListExtra(Intent.EXTRA STREAM) 


if (imageUris != null) { 
// Update UI to reflect multiple images being shared 


请 注意 ， 由 于 无 法 知道 其 他 程序 发 送 过 来 的 数据 内 容 是 文本 还 是 其 他 类 型 的 数据 ， 若 数据 量 
巨大 ， 则 需要 大 量 处 理 时 间 ， 因 此 我 们 应 避免 在 UI 线程 里 面 去 处 理 那 些 获 取 到 的 数据 。 


更 新 UI 可 以 像 更 新 EditText 一 样 简单 ， 也 可 以 是 更 加 复杂 一 点 的 操作 ， 例 如 过 滤 出 感 兴 趣 的 图 
片 。 这 完全 取决 于 我 们 的 应 用 接 下 来 要 做 些 什么 。 


添加 一 个 简便 的 分 享 功能 


编写 :kesenhoo - Æ X:http://developer.android.com/training/sharing/shareaction.html 


Android4.0 之 后 系统 中 ActionProvider 的 引入 使 在 ActionBar 中 添加 分 享 功 能 变 得 更 为 简单 。 它 
会 handle 出 现 share 功 能 的 appearance 与 behavior。 在 ShareActionProvider 的 例子 里 面 ， 我 们 
只 需要 提供 一 个 share intent， 剩 下 的 就 交 给 ShareActionProvider 来 做 。 


A 
o 
LJ 


+ " 
3 mu Gmail 


ih ; Bluetooth 


"E. Picasa 


See al 





更 新 菜单 声 — Menu Declarations) 


使 用 ShareActionProvider 的 第 一 步 ， 在 menu resources E item P X 


3L android:actionProviderClass s 9 


«menu xmlns:android="http://schemas.android.com/apk/res/android"> 
«item android:id-"Q-id/menu item share" 
android:showAsAction-"ifRoom" 
android:title-"Share" 
android:actionProviderClass-"android.widget.ShareActionProvider" /> 


«/menu» 


这 表明 了 该 iem 的 appearance 与 function 需 要 与 ShareActionProvider 匹 配 。 此 外 ， 你 还 需要 告 
诉 provider 想 分 享 的 内 容 。 


Set the Share Intent( 设 置 分 享 的 intent) 


为 了 实现 ShareActionProvider 的 功能 ， 我 们 必须 为 它 提供 一 个 intent。 该 share intent 应 该 像 第 
一 课 讲 的 那样 ， 带 有 AcTION_SEND 和 附加 数据 (例如 EXTRA_TEXT 与 EXTRA_STREAM ) 的 。 使 用 
ShareActionProvider 的 例子 如 下 : 


private ShareActionProvider mShareActionProvider; 


@Override 

public boolean onCreateOptionsMenu(Menu menu) { 
// Inflate menu resource file. 
getMenuInflater().inflate(R.menu.share menu, menu); 


// Locate MenuItem with ShareActionProvider 
MenuItem item - menu.findItem(R.id.menu item share); 


// Fetch and store ShareActionProvider 
mShareActionProvider - (ShareActionProvider) item.getActionProvider(); 


// Return true to display menu 
return enue: 


// Call to update the share intent 
private void setShareIntent(Intent shareIntent) { 
if (mShareActionProvider != null) { 
mShareActionProvider.setShareIntent(shareIntent); 


也 许 在 创建 菜单 的 时 候 仅 仅 需要 设置 一 次 share intent 就 满足 需求 了 ， 或 者 说 我 们 可 能 想 先 设 
置 share intent， 然 后 根据 UI 的 变化 来 对 intent 进 行 更 新 。 例 如 ， 当 在 Gallery 里 面 全 图 查看 照片 
的 时 候 ，share intent 会 在 切换 图 片 时候 进 行 改变 。 更 多 关于 ShareActionProvider 的 内 容 ， 请 
查看 Action Bar 。 


人 入 Š 3 
TFL 
编写 :jdneo - 原文 :http://developer.android.com/training/secure-file-sharing/index.html 
g 


一 个 程序 经 常 需要 向 其 他 程序 提供 一 个 甚至 多 个 文件 。 例 如 ， 当 我 们 用 图 片 编辑 器 编辑 图 片 
时 ， 被 编辑 的 图 片 往往 由 图 库 应 用 程序 所 提供 ; 再 比如 ， 文 件 管理 器 会 允许 用 户 在 外 部 存储 
的 不 同 区 域 之 间 复 制 粘贴 文件 。 这 里 ， 我 们 提出 一 种 让 应 用 程序 可 以 分 享 文件 的 方法 : BPS 
发 送 文件 的 应 用 程序 对 索取 文件 的 应 用 程序 所 发 出 的 文件 请 求 进 行 响应 。 

在 任何 情况 下 ， 将 文件 从 我 们 的 应 用 程序 发 送 至 其 它 应 用 程序 的 唯一 的 安全 方法 是 向 接收 文 
件 的 应 用 程序 发 送 这 个 文件 的 content URI， 并 对 该 URI 授 予 临 时 访问 权限 。 具 有 URI 临 时 访问 
权限 的 content URI 是 安全 的 ， 因 为 他 们 仅 应 用 于 接收 这 个 URI 的 应 用 程序 ， 并 且 会 自动 过 
期 。Android 的 FileProvider 组 件 提供 了 getUriForFile() 方 法 创建 一 个 文件 的 content URI ° 


如 果 和 希望 在 应 用 之 间 共 享 少量 的 文本 或 者 数字 等 类 型 的 数据 ， 应 使 用 包含 该 数据 的 Intent。 要 
学 习 如 何 通 过 Intent 发 送 简单 数据 ， 可 以 阅读 : Sharing Simple Data ° 


本 课 主 要 介绍 了 如 何 使 用 Android 的 FileProvider 组 件 所 创建 的 content URI 在 应 用 之 问安 全 的 
共享 文件 。 当 然 ， 要 做 到 这 一 点 ， 还 需要 给 接收 文件 的 应 用 程序 访问 的 这 些 content URI} P 
临时 访问 权限 。 


Lessons 


文 
学 习 如 何 配置 应 用 程序 使 得 它们 可 以 分 享 文件 。 
e 分 享 文件 
学 习 分 享 文件 的 三 个 步骤 : 


o 生成 文件 的 content URI ; 
o 授予 URI 的 临时 访问 权限 ; 
o 将 URI 发 送 给 接收 文件 的 应 用 程序 。 


。 请 求 分 享 一 个 文件 


学 习 如 何 向 其 他 应 用 程序 请 求 文件 ， 如 何 接收 该 文件 的 content URI， 以 及 如 何 使 用 
content URI 打 开 该 文件 。 


e 获取 文件 信息 


学 习 应 用 程序 如 何 通过 FileProvider 提 供 的 content URI 获 取 文 件 的 信息 : 例如 MIME 类 
型 ， 文 件 大 小 等 。 


建立 文件 分 至 


编写 :jdneo - 原文 :http://developer.android.com/training/secure-file-sharing/setup- 
sharing.html 


为 了 将 文件 安全 地 从 我 们 的 应 用 程序 共享 给 其 它 应 用 程序 ， 我 们 需要 对 自己 的 应 用 进行 配置 
来 提供 安全 的 文件 句柄 (Content URI 的 形式 ) 。Android 的 FileProvider 组 件 会 基于 在 XML 文 
件 中 的 具体 配置 为 文件 创建 Content URI。 本 课 将 介绍 如 何在 应 用 程序 中 添加 FileProvider 的 黑 
认 实 现 ， 以 及 如 何 指定 要 共享 的 文件 。 


Note:FileProvider 类 隶属 于 v4 Support Library 库 。 关 于 如 何在 应 用 程序 中 包含 该 库 ， 请 
参考 : Support Library Setup ° 


指定 FileProvider 


为 了 给 应 用 程序 定义 一 个 FileProvider， 需 要 在 Manifest 清 单 文件 中 定义 一 个 entry， 该 entry 指 
明了 需要 使 用 的 创建 Content URI 的 Authority。 此 外 ， 还 需要 一 个 XML 文 件 的 文件 名 ， 该 XML 
文件 指定 了 我 们 的 应 用 可 以 共享 的 目录 路 径 。 


下 例 展示 了 如 何在 清单 文件 中 添加 <provider> 标签 ， 来 指定 FileProvider 类 ，Authority 及 XML 
文件 名 : 


«manifest xmlns:android-"http://schemas.android.com/apk/res/android" 
package="com.example.myapp"> 
<application 
Age 
«provider 

android:name-"android.support.v4.content.FileProvider" 
android:authorities-"com.example.myapp.fileprovider" 
android:grantUriPermissions-"true" 
android:exported-"false"» 

«meta-data 
android:name-"android.support.FILE PROVIDER PATHS" 
android: resource="@xml/filepaths" /> 

</provider> 


</application> 
</manifest> 


这 里 ，android:authorities 字 段 指 定 了 希望 使 用 的 Authority， 该 Authority 针 对 于 FileProvider 所 
生成 的 content URI。 本 例 中 的 Authority 是 “com.example.myapp.fileprovider。 对 于 自己 的 应 
用 ， 要 在 我 们 的 应 用 程序 包 名 (android:package 的 值 ) 之 后 继续 追加 “fileprovider 来 指定 


Authority。 要 更 多 关于 Authority 的 知识 ， 请 参考 : Content URIs， 以 及 android:authorities 。 


«provider» 下 的 <meta-data> 指向 了 一 个 XML 文件 ， 该 文件 指定 了 我 们 希望 共享 的 目录 路 
径 。android:resource” 属 性 字段 是 这 个 文件 的 路 径 和 名 字 〈 无 xml" 后 级 ) 。 该 文件 的 内 容 将 
在 下 一 节 讨 论 9 


指定 可 共和 至 目录 路 径 


一 旦 在 Manifest 清 单 文 件 中 为 自己 的 应 用 添加 了 FileProvider， 就 需要 指定 我 们 希望 共享 文件 

的 目录 路 径 。 为 指定 该 路 径 ， 首 先 要 在 "res/xml/" 下 创建 文件 "filepaths.xml”。 在 这 个 文件 中 ， 

为 每 一 个 想 要 共享 目录 添加 一 个 XML 标签 。 下 面 的 是 一 个 "res/xmlfilepaths.xml" 的 内 容 样 例 。 
这 个 例子 也 说 明了 如 何在 内 部 存储 区 域 共享 一 个 files/”" 目 录 的 子 目录 : 


<paths> 
<files-path path="images/" name="myimages" /> 
</paths> 


在 这 个 例子 中 ， <files-path> 标签 共享 的 是 在 我 们 应 用 的 内 部 存储 中 “files/” 目 录 下 的 目 

录 。“path” 属 性 字段 指出 了 该 子 目 录 为 “files/”" 目 录 下 的 子 目 录 “images/”"。“name" 属 性 字段 告知 
FileProvider 在 “files/images/" 子 目录 中 的 文件 的 Content URI 添 加 路 径 分 段 (path segment) 
标记 : “myimages”。 


«paths» 标签 可 以 有 多 个 子 标签 ， 每 一 个 子 标签 用 来 指定 不 同 的 共享 目录 。 除 了 <files- 
path> 标签 ， 还 可 以 使 用 <external-path> 来 共享 位 于 外 部 存储 的 AR: 另外 ” «cache- 
path» 标签 用 来 共享 在 内 部 缓存 目录 下 的 子 目 录 。 更 多 关于 指定 共享 目录 子 标签 的 知识 请 参 
考 : FileProvider ° 


Note: XML 文件 是 我 们 定义 共享 目录 的 唯一 方式 ， 不 可 以 用 代码 的 形式 添加 目录 。 


现在 我 们 有 一 个 完整 的 FileProvider 声 明 ， 它 在 应 用 程序 的 内 部 存储 中 “files/" 目 录 或 其 子 目录 
下 创建 文件 的 Content URI。 当 我 们 的 应 用 为 一 个 文件 创建 了 Content URI， 该 Content URI 
会 包含 下 列 信息 : 


e <provider> 标签 中 指定 的 Authority (“com.example.myapp.fileprovider”) 
e 路 径 “myimages/”; 
e 文件 的 名 字 。 


例如 ， 如 果 本 课 的 例子 定义 了 一 个 FileProvider， 然 后 我 们 需要 一 个 文件 “default image.jpg” 的 
Content URI，FileProvider 会 返回 如 下 URI : 


content://com.example.myapp.fileprovider/myimages/default image.jpg 
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2 3 xt 


编写 :jdneo - /$ X:http://developer.android.com/training/secure-file-sharing/sharing- 
file.html 


对 应 用 程序 进行 配置 ， 使 得 它 可 以 使 用 Content URI 来 共享 文件 后 ， 其 就 可 以 响应 其 他 应 用 程 
序 的 获取 文件 的 请 求 了 。 一 种 响应 这 些 请 求 的 方法 是 在 服务 端 应 用 程序 提供 一 个 可 以 由 其 他 
应 用 激活 的 文件 选择 接口 。 该 方法 可 以 允许 客户 端 应 用 程序 让 用 户 从 服务 端 应 用 程序 选择 一 
个 文件 ， 然 后 接收 这 个 文件 的 Content URI 。 


本 课 将 会 展示 如 何在 应 用 中 创建 一 个 用 于 选择 文件 的 Activity， 来 响应 这 些 获取 文件 的 请 求 。 


授 收 文件 请 > 


为 了 从 客户 端 应 用 程序 接收 一 个 文件 获取 请 求 并 以 Content URI 的 形式 进行 响应 ， 我 们 的 应 用 
程序 应 该 提供 一 个 选择 文件 的 Activity。 客 户 端 应 用 程序 通过 调用 startActivityForResult() 方 法 
启动 这 一 Activity。 该 方法 包含 了 一 个 具有 ACTION_PICKAction 的 Intent 参 数 。 当 客户 端 应 用 

程序 调用 了 startActivityForResult()， 我 们 的 应 用 可 以 向 客户 端 应 用 程序 返回 一 个 结果 ， 该 结 

果 即 用 户 所 选择 的 文件 所 对 应 的 Content URI ° 


关于 如 何在 客户 端 应 用 程序 实现 文件 获取 请 求 ， 请 参考 : 请 求 分 享 一 个 文件 。 


创建 一 个 选择 文件 的 Activity 


为 建立 一 个 选择 文件 的 Activity， 首 先 需要 在 Manifest 清 单 文 件 中 定义 Activity， 在 其 Intent 过 滤 
ZP > LAZACTION PICKAction£ CATEGORY DEFAULTZeCATEGORY OPENABLE X & 
种 Category。 另 外 ， 还 需要 为 应 用 程序 设置 MIME 类 型 过 滤器 ， 来 表明 我 们 的 应 用 程序 可 以 向 
其 他 应 用 程序 提供 哪 种 类 型 的 文件 。 下 面 这 段 代码 展示 了 如 何在 清单 文件 中 定义 新 的 Activity 
和 Intent 过 滤器 : 


«manifest xmlns:android-"http://schemas.android.com/apk/res/android"» 
«application» 


«activity 
android:name=".FileSelectActivity" 
android: label="File Selector" > 
<intent-filter> 
<action 
android:name="android.intent.action.PICK"/> 
<category 
android: name="android.intent.category.DEFAULT"/> 
<category 
android: name="android.intent.category.OPENABLE"/> 
<data android:mimeType="text/plain"/> 
<data android:mimeType="image/*"/> 
</intent-filter> 
</activity> 


在 代码 中 定义 文件 选择 Activity 


下 面 ， 定 义 一 个 Activity 子 类 ， 用 于 显示 在 内 部 存储 的 "files/images/" 目 录 下 可 以 获得 的 文件 ， 
然后 允许 用 户 选择 期 望 的 文件 。 下 面 代码 展示 了 如 何 定义 该 Activity， 并 令 其 响应 用 户 的 选 


择 : 


public class MainActivity extends Activity { 
// The path to the root of this app's internal storage 
private File mPrivateRootDir; 
// The path to the "images" subdirectory 
private File mImagesDir; 
// Array of files in the images subdirectory 
File[] mImageFiles; 
// Array of filenames corresponding to mImageFiles 
String[] mImageFilenames; 
// Initialize the Activity 
@Override 
protected void onCreate(Bundle savedInstanceState) { 


// Set up an Intent to send back to apps that request a file 
mResultIntent - 
new Intent("com.example.myapp.ACTION RETURN FILE"); 

// Get the files/ subdirectory of internal storage 
mPrivateRootDir - getFilesDir(); 
// Get the files/images subdirectory; 
mImagesDir = new File(mPrivateRootDir, "images"); 
// Get the files in the images subdirectory 
mImageFiles = mImagesDir.listFiles(); 
// Set the Activity's result to null to begin with 
setResult(Activity.RESULT CANCELED, null); 
/* 

* Display the file names in the ListView mFileListView. 

* Back the ListView with the array mImageFilenames, which 

* you can create by iterating through mImageFiles and 

* calling File.getAbsolutePath() for each File 

BWA 


响应 一 个 文件 选择 


一 旦 用 户 选择 了 一 个 被 共享 的 文件 ， 我 们 的 应 用 程序 必须 明确 哪个 文件 被 选择 了 ， 并 为 该 文 
件 生成 一 个 对 应 的 Content URI。 如 果 我 们 的 Activity 在 ListView 中 显示 了 可 获得 文件 的 清单 ， 
那么 当 用 户 点 击 了 一 个 文件 名 时 ， 系 统 会 调用 方法 onltemClick()， 在 该 方法 中 可 以 获取 被 选择 
的 文件 。 


在 onltemClick() 中 ， 根 据 被 选中 文件 的 文件 名 获取 一 个 File 对 象 ， 然 后 将 其 作为 参数 传递 给 
getUriForFile()， 另 外 还 需 传 入 的 参数 是 在 «provider» 标签 中 为 FileProvider 所 指定 的 
Authority > HAR @ 8 Content URI 包 含 了 相应 的 Authority， 一 个 对 应 于 文件 目录 的 路 径 标记 
(如 在 XML meta-data 中 定义 的 ) ， 以 及 包含 扩展 名 的 文件 名 。 有 关 FileProvider 如 何 基 于 
XML meta-data 将 目录 路 径 与 路 径 标 记 进行 匹配 的 知识 ， 可 以 阅读 : 指定 可 共享 目录 路 径 。 


下 例 展 示 了 如 何 检测 选中 的 文件 并 且 获 得 它 的 Content URI : 


protected void onCreate(Bundle savedInstanceState) { 


// Define a listener that responds to clicks on a file in the ListView 
mFileListView.setOnItemClickListener( 
new AdapterView.OnItemClickListener() { 
@Override 
/* 
* when a filename in the ListView is clicked, get its 
* content URI and send it to the requesting app 
SA 
public void onItemClick(AdapterView<?> adapterView, 
View view, 
int position, 
long rowId) ( 
/* 
* Get a File for the selected file name. 
* Assume that the file names are in the 
* mImageFilename array. 
due 
File requestFile - new File(mImageFilename[position]); 
/* 
* Most file-related method calls need to be in 
* try-catch blocks. 
A 
// Use the FileProvider to get a content URI 
TIVA 
fileUri = FileProvider.getUriForFile( 
MainActivity.this, 
"com.example.myapp.fileprovider", 
requestFile); 
} catch (IllegalArgumentException e) { 
Log.e("File Selector", 
"The selected file can't be shared: " + 
clickedFilename); 


3); 


记 住 ， 我 们 能 生成 的 那些 Content URI 所 对 应 的 文件 ， 必 须 是 那些 在 meta-data 文 件 中 包 

4 «paths» 标签 的 目录 内 的 文件 ， 这 方面 知识 在 Specify Sharable Directories 中 已 经 讨论 过 。 
如 果 调 用 getUriForFile() 方 法 所 要 获取 的 文件 不 在 我 们 指定 的 目录 中 ， 会 收 到 一 
““\llegalArgumentException ° 


为 文件 授权 


> 


I 


现在 已 经 有 了 想 要 共享 给 其 他 应 用 程序 的 文件 所 对 应 的 Content URI， 我 们 需要 允许 客户 端 应 
用 程序 访问 这 个 文件 。 为 了 达到 这 一 目的 ， 可 以 通过 将 Content URI 添 加 至 一 个 Intent 中 ， 然 


后 为 该 Intent 设 置 权限 标记 。 所 授予 的 权限 是 临时 的 ， 并 且 当 接收 文件 的 应 用 程序 的 任务 栈 终 
止 后 ， 会 自动 过 期 。 


下 例 展 示 了 如 何 为 文件 设置 读 权 限 : 


protected void onCreate(Bundle savedInstanceState) { 


// Define a listener that responds to clicks in the ListView 
mFileListView.setOnItemClickListener( 
new AdapterView.OnItemClickListener() { 
@Override 
public void onItemClick(AdapterView<?> adapterView, 
View view, 
int position, 
long rowId) { 


if (fileUri != null) { 
// Grant temporary read permission to the content URI 
mResultIntent.addFlags( 
Intent.FLAG GRANT READ URI PERMISSION); 





3); 


Caution : 调用 setFlags() 来 为 文件 授予 临时 被 访问 权限 是 唯一 的 安全 的 方法 。 尽 量 避 免 
对 的 Content URI 调 用 Context.grantUriPermission()， 因 为 通过 该 方法 授予 的 权限 ， 


a 4b3 


只 能 通过 调用 Context.revokeUriPermission() 来 撤销 。 


与 请 求 应 用 共享 文件 


为 了 向 请 求 文件 的 应 用 程序 提供 其 需要 的 文件 ， 我 们 将 包含 了 Content URI 和 相应 权限 的 
Intent 传 递 给 setResult()。 当 定义 的 Activity 结 束 后 ， 系 统 会 把 这 个 包含 了 Content URI 的 Intent 
传递 给 客户 端 应 用 程序 。 下 例 展 示 了 其 中 的 核心 步骤 : 


protected void onCreate(Bundle savedInstanceState) { 


// Define a listener that responds to clicks on a file in the ListView 
mFileListView.setOnItemClickListener( 
new AdapterView.OnItemClickListener() { 
@Override 
public void onItemClick(AdapterView<?> adapterView, 
View view, 
int position, 
long rowId) { 


if (fileUri != null) { 


// Put the Uri and MIME type in the result Intent 
mResultIntent.setDataAndType( 
fileuri, 
getContentResolver().getType(fileUri)); 
// Set the result 
MainActivity.this.setResult(Activity.RESULT OK, 
mResultIntent); 
} else { 
mResultIntent.setDataAndType(null, ""); 
MainActivity.this.setResult(RESULT CANCELED, 
mResultIntent); 


3); 


当 用 户 选择 好 文件 后 ， 我 们 应 该 向 用 户 提供 一 个 能 够 立即 回 到 客户 端 应 用 程序 的 方法 。 一 种 
实现 的 方法 是 向 用 户 提 供 一 个 名 选 框 或 者 一 个 完成 按钮 。 可 以 使 用 按钮 的 android:onClick 属 性 
字段 为 它 关联 一 个 方法 。 在 该 方法 中 ， 调 用 finish()。 例 如 : 


public void onDoneClick(View v) { 
// Associate a method with the Done button 
finish(); 


人 人 


编写 :jdneo - 原文 :http://developer.android.com/training/secure-file-sharing/request- 
file.html 


当 一 个 应 用 程序 希望 访问 由 其 它 应 用 程序 所 共享 的 文件 时 ， 请 求 应 用 程序 (客户 端 ) 经 常会 
向 其 它 应 用 程序 (服务 端 ) 发 送 一 个 文件 请 求 。 多 数 情况 下 ， 该 请 求 会 导致 在 服务 端 应 用 程 
序 中 局 动 一 个 Activity， 该 Activity 中 会 显示 可 以 共享 的 文件 。 当 服务 端 应 用 程序 向 客户 端 应 用 
程序 返回 了 文件 的 Content URI 后 ， 用 户 即 可 开始 选择 文件 。 


本 课 将 展示 一 个 客户 端 应 用 程序 应 该 如 何 向 服务 端 应 用 程序 请 求 一 个 文件 ， 接 收服 务 端 应 用 
程序 发 来 的 Content URI， 然 后 使 用 这 个 Content URI 打 开 这 个 文件 。 


发 送 一 个 文件 请 求 


为 了 向 服务 端 应 用 程序 发 送 文件 请 求 ， 在 客户 端 应 用 程序 中 ， 需 要 调用 startActivityForResult) 
方法 ， 同 时 传递 给 这 个 方法 一 个 Intent 参 数 ， 它 包含 了 客户 端 应 用 程序 能 处 理 的 某 个 Action ， 
比如 ACTION_PICK 及 一 个 MIME 类 型 。 


例如 ， 下 面 的 代码 展示 了 如 何 向 服务 端 应 用 程序 发 送 一 个 Intent， 来 启动 在 分 享 文件 中 提 到 的 
Activity : 


public class MainActivity extends Activity { 
private Intent mRequestFileIntent; 
private ParcelFileDescriptor mInputPFD; 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState) ; 
setContentView(R.layout.activity main); 
mRequestFileIntent - new Intent(Intent.ACTION PICK); 
mRequestFileIntent.setType("image/jpg"); 


} 


protected void requestFile() { 
pan 
* When the user requests a file, send an Intent to the 


* 


server app. 
DSS 

572 

startActivityForResult(mRequestFileIntent, 0); 


访问 请 求 的 文件 


当 服 务 端 应 用 程序 向 客户 端 应 用 程序 发 回 包含 Content URI 的 Intent 时 ， 该 Intent 会 传递 给 客户 
端 应 用 程序 重 写 的 onActivityResult() 方 法 当中 。 一 旦 客户 端 应 用 程序 拥有 了 文件 的 Content 
URI，,， 它 就 可 以 通过 获取 其 FileDescriptor 访 问 文件 了 。 


这 一 过 程 中 不 用 过 多 担心 文件 的 安全 问题 ， 因 为 客户 端 应 用 程序 所 收 到 的 所 有 数据 只 有 文件 
的 Content URI 而 已 。 由 于 URI 不 包含 目录 路 径 信息 ， 客 户 端 应 用 程序 无 法 查询 或 打开 任何 服 
务 端 应 用 程序 的 其 他 文件 。 客 户 端 应 用 程序 仅仅 获取 了 这 个 文件 的 访问 渠道 以 及 由 服务 端 应 
用 程序 授予 的 访问 权限 。 同 时 访问 权限 是 临时 的 ， 一 旦 这 个 客户 端 应 用 的 任务 栈 结 束 了 ， 这 
个 文件 将 无 法 再 被 除 服务 端 应 用 程序 之 外 的 其 他 应 用 程序 访问 。 


下 面 的 例子 展示 了 客户 端 应 用 程序 应 该 如 何 处 理发 自 服务 端 应 用 程序 的 Intent， 以 及 客户 端 应 
用 程序 如 何 使 用 Content URI 获 取 FileDescriptor : 


* When the Activity of the app that hosts files sets a result and calls 
* finish(), this method is invoked. The returned Intent contains the 
* content URI of a selected fille. The result code indicates if the 
* selection worked or not. 
yf, 
@Override 
public void onActivityResult(int requestCode, int resultCode, 
Intent returnIntent) { 
// If the selection didn't work 
if (resultCode !- RESULT OK) { 
// Exit without doing anything else 
return; 
+ else f 
// Get the file's content URI from the incoming Intent 
Uri returnUri = returnIntent.getData(); 
/* 
* Try to open the file for "read" access using the 
* returned URI. If the file isn't found, write to the 
* error log and return. 
v 
try { 
/* 
* Get the content resolver instance for this context, and use it 
* to get a ParcelFileDescriptor for the file. 
yf 
mInputPFD = getContentResolver().openFileDescriptor(returnUri, "r"); 
} catch (FileNotFoundException e) { 
e.printStackTrace(); 
Log.e("MainActivity", "File not found."); 
return; 
} 
// Get a regular file descriptor for the file 
FileDescriptor fd = mInputPFD.getFileDescriptor(); 


openFileDescriptor() 方 法 返回 一 个 文件 的 ParcelFileDescriptor 对 象 。 客 户 端 应 用 程序 从 该 对 
象 中 获取 FileDescriptor 对 象 ， 然 后 利用 该 对 象 读 取 这 个 文件 了 。 
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获取 文件 信息 


编写 :jdneo - Æ X:http://developer.android.com/training/secure-file-sharing/retrieve- 
info.html 
当 一 个 客户 端 应 用 程序 拥有 了 文件 的 Content URI 之 后 ， 它 就 可 以 获取 该 文件 并 进行 下 一 步 的 
工作 了 ， 但 在 此 之 前 ， 客 户 端 应 用 程序 还 可 以 向 服务 端 应 用 程序 获取 关于 文件 的 信息 ， 包 括 
文件 的 数据 类 型 和 文件 大 小 等 等 。 数 据 类 型 可 以 帮助 客户 端 应 用 程序 确定 自己 能 否 处 理 该 文 
件 ， 文 件 大 小 能 帮助 客户 端 应 用 程序 为 文件 设置 合理 的 缓冲 区 。 


本 课 将 展示 如 何 通过 查询 服务 端 应 用 程序 的 FileProvider 来 获取 文件 的 MIME 类 型 和 文件 大 
小 o 


获取 文件 的 MIME 类 型 


客户 端 应 用 程序 可 以 通过 文件 的 数据 类 型 判断 自己 应 该 如 何 处 理 这 个 文件 的 内 容 。 客 户 端 应 
用 程序 可 以 通过 调用 ContentResolver.getType() 方 法 获得 Content URI 所 对 应 的 文件 数据 类 
型 。 该 方法 返回 文件 的 MIME 类 型 。 默 认 情 况 下 ， 一 个 FileProvider 通 过 文件 的 后 缀 名 来 确定 


XMIME X 7I! © 


下 例 展 示 了 当 服 务 端 应 用 程序 将 Content URI 返 回 给 客户 端 应 用 程序 后 ， 客 户 端 应 用 程序 应 该 
如 何 获取 文件 的 MIMIE 类 型 : 


* Get the file's content URI from the incoming Intent, then 
* get the file's MIME type 

ny 

Uri returnUri - returnIntent.getData(); 

String mimeType = getContentResolver().getType(returnUri); 


x ` . 
获取 文件 名 及 文件 大 小 

FileProvider 类 有 一 个 query() 方 法 的 黑 认 实现 ， 它 返回 一 个 Cursor 对 象 ， 该 Cursor 对 象 包含 了 
Content URI 所 关联 的 文件 的 名 称 和 大 小 。 默 认 的 实现 返回 下 面 两 列 信息 : 

DISPLAY NAME 


文件 名 ，String 类 型 。 这 个 值 和 File.getName() 所 返回 的 值 一 样 。 


SIZE 
文件 大 小 ， 以 字 节 为 单位 ，long 类 型 。 这 个 值 和 File.length() 所 返回 的 值 一 样 。 


客户 端 应 用 可 以 通过 将 query() 的 除了 Content URI 之 外 的 其 他 参数 都 设置 为 "null"， 来 同时 获取 
文件 的 名 称 (DISPLAY NAME) 和 大 小 (SIZE) 。 例 如 ， 下 面 的 代码 获取 一 个 文件 的 名 称 和 
大 小 ， 然 后 在 两 个 TextView 中 将 他 们 显示 出 来 : 


/* 

* Get the file's content URI from the incoming Intent, 

* then query the server app to get the file's display name 

= and ‘sizer 

i 
Uri returnUri - returnIntent.getData(); 
Cursor returnCursor - 

getContentResolver().query(returnUri, null, null, null, null); 

/* 

* Get the column indexes of the data in the Cursor, 

* move to the first row in the Cursor, get the data, 

* and display it. 

ky 
int nameIndex - returnCursor.getColumnIndex(OpenableColumns.DISPLAY NAME); 
int sizeIndex - returnCursor.getColumnIndex(OpenableColumns.SIZE); 
returnCursor.moveToFirst(); 
TextView nameView - (TextView) findViewById(R.id.filename text); 
TextView sizeView - (TextView) findViewById(R.id.filesize text); 
nameView.setText(returnCursor.getString(nameIndex)); 
sizeView.setText(Long.toString(returnCursor.getLong(sizeIndex))); 


使 用 NFC 分 享 文件 


编写 :jdneo - 原文 :http://developer.android.com/training/beam-files/index.html 


Android 人 允许 我 们 通过 Android Beam 文 件 传输 功能 在 设备 之 间 传 送 大 文件 。 该 功能 具有 简单 的 
API， 它 使 得 用 户 仅 需要 通过 一 些 简单 的 触 控 操 作 就 能 启动 文件 传输 过 程 。Android Beam 会 
自动 地 将 文件 从 一 台 设 备 找 贝 至 另 一 台 设 备 中 ， 并 在 完成 时 告知 用 户 。 


Android Beam 文 件 传 输 API 可 以 用 来 处 理 规模 较 大 的 数据 ， 而 在 Android4.0 (API Level 14) 

引入 的 Android Beam NDEF 传 输 API 则 用 来 处 理 规模 较 小 的 数据 ， 如 URI 或 者 消息 数据 等 。 另 
外 ，Android Beam 仅 仅 只 是 Android NFC 框 架 提供 的 众多 特性 之 一 ， 它 允许 我 们 从 NFC 标 签 
中 读 取 NDEF 消 息 。 更 多 有 关 Android Beam 的 知识 ， 请 参考 : Beaming NDEF Messages to 
Other Devices。 更 多 有 关 NFC 框 架 的 知识 ， 请 参考 : Near Field Communication ° 


Lessons 
e 发 送 文件 给 其 他 设备 

学 习 如 何 配 置 应 用 程序 ， 使 其 可 以 发 送 文件 给 其 他 设备 。 
e 接收 其 他 设备 的 文件 


学 习 如 何 配置 应 用 程序 ， 使 其 可 以 接收 其 他 设备 发 送 的 文件 。 


发 送 文件 给 其 他 设备 


编写 :jdneo - /$ xc:http://developer.android.com/training/beam-files/sending-files.html 


这 节 课 将 展示 如 何 通过 Android Beam 文 件 传输 向 另 一 台 设 备 发 送 大 文件 。 要 发 送 文件 ， 首 先 
应 声明 使 用 NFC 和 外 部 存储 的 权限 ， 我 们 需要 测试 一 下 自己 的 设备 是 否 支 持 NFC， 这 样 才能 
够 将 文件 的 URI 提 供给 Android Beam 文 件 传输 。 


使 用 Android Beam 文 件 传输 功能 必须 满足 以 下 要 求 : 


1. Android Beam 文 件 传输 功能 传输 大 文件 必须 在 Android 4.1 (API Level 16) 及 以 上 版 本 
的 Android 系 统 中 使 用 。 

2. 和 硕 望 传送 的 文件 必须 放置 于 外 部 存储 。 更 多 关于 外 部 存储 的 知识 ， 请 参考 : Using the 
External Storage ° 

3. 和 硕 望 传送 的 文件 必须 是 全 局 可 读 的 。 我 们 可 以 通过 File.setReadable(true,false) 来 为 文件 
设置 相应 的 读 权 限 。 

4. 必须 提供 待 传输 文件 的 File URI。Android Beam 文 件 传输 无 法 处 理 
由 FileProvider.getUriForFile 生 成 的 Content URI ° 


LE X4 4 + 
在 清单 文件 中 声明 
首先 ， 编 辑 Manifest 清 单 文件 来 声明 应 用 程序 所 需要 的 权限 和 功能 。 


声明 权限 


为 了 允许 应 用 程序 使 用 Android Beam 文 件 传输 控制 NFC 从 外 部 存储 发 送 文件 ， 必 须 在 应 用 程 
序 的 Manifest 清 单 文件 中 声明 下 面 的 权限 : 


NFC 


允许 应 用 程序 通过 NFC 发 送 数 据 。 为 声明 该 权限 ， 要 添加 下 面 的 标签 作为 一 个 <manifest> 标 
签 的 子 标签 : 


«uses-permission android:name-"android.permission.NFC" /> 


READ EXTERNAL STORAGE 


允许 应 用 读 取 外 部 存储 。 为 声明 该 权限 ， 要 添加 下 面 的 标签 作为 一 个 <manifest> 标签 的 子 标 
签 : 


Sh 


«uses-permission 
android:name-"android.permission.READ EXTERNAL STORAGE" /> 


Note : 对 于 Android 4.2.2 (API Level 17) 及 之 前 版 本 的 系统 ， 这 个 权限 不 是 必需 的 。 
在 后 续 版 本 的 系统 中 ， 若 应 用 程序 需要 读 取 外 部 存储 ， 可 能 会 需要 申明 该 权限 。 为 保证 
将 来 程序 稳定 性 ， 建 议 在 该 权限 申明 变 成 必需 的 之 前 ， 先 在 清单 文件 中 声明 。 

指定 NFC 功 能 

通过 添加 <uses-feature> 标签 作为 一 个 <manifest> 标签 的 子 标签 ， 指 定 我 们 的 应 用 程序 使 用 


NFC。 设 置 android:required 属性 字段 为 true ， 使 得 我 们 的 应 用 程序 只 有 在 NFC 可 以 使 用 时 


下 面 的 代码 展示 了 如 何 指定 <uses-feature> 标签 : 


«uses-feature 
android:name-"android.hardware.nfc" 
android:required-"true" /» 


注意 ， 如 果 应 用 程序 将 NFC 作 为 一 个 可 选 的 功能 ， 期 望 在 NFC 不 可 使 用 时 程序 还 能 继续 执 
行 ， 我 们 就 应 该 将 android:required 属性 字段 设 为 false ， 然 后 在 代码 中 测试 NFC 的 可 用 
小 o 
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& T Android Beam x 4f 44 R Aé 4€ Android 4.1 (API Level 16) 及 以 上 的 平台 使 用 ， 如 果 应 
用 将 Android Beam 文 件 传 输 作 为 一 个 不 可 缺少 的 核心 模块 ， 那 么 我 们 必须 指定 <uses-sdk> 标 
签 为 : android:minSdkVersion="16"。 或 者 可 以 将 android:minSdkVersion 设 置 为 其 它 值 ， 然 
后 在 代码 中 测试 平台 版 本 ， 这 部 分 内 容 将 在 下 一 节 中 展开 。 

Ml aX 4 时 不 ' 5 人 

测试 设备 是 否 支持 Android Beam 文 件 传 输 

应 使 用 以 下 标签 使 得 在 Manifest 清 单 文件 中 指定 NFC 是 可 选 的 : 


«uses-feature android:name-"android.hardware.nfc" android:required-"false" /» 


如 果 设 置 了 android:required="false"， 则 我 们 必须 在 代码 中 测试 设备 是 否 支持 NFC 和 Android 
Beam ft 4 di © 


为 在 代码 中 测试 是 否 支持 Android Beam 文 件 传 输 ， 我 们 先 通过 
PackageManagerhasSystemFeature() 和 参数 FEATURE_NFC 测 试 设 备 是 否 支 持 NFC。 下 一 
步 ， 通 过 SDK_INT 的 值 测试 系统 版 本 是 否 支持 Android Beam 文 件 传 输 。 如 果 设 备 支持 
Android Beam 文 件 传 输 ， 那 么 获得 一 个 NFC 控 制 器 的 实例 ， 它 能 允许 我 们 与 NFC 硬 件 进 行 通 
信 ， 如 下 所 示 : 


public class MainActivity extends Activity { 


NfcAdapter mNfcAdapter; 
// Flag to indicate that Android Beam is available 
boolean mAndroidBeamAvailable = false; 


@Override 
protected void onCreate(Bundle savedInstanceState) { 


// NFC isn't available on the device 
if (!PackageManager .hasSystemFeature(PackageManager.FEATURE_NFC)) { 
/* 
* Disable NFC features here. 
* For example, disable menu items or buttons that activate 
* NFC-related features 
27 


// Android Beam file transfer isn't supported 
) eise if (Build.VERSION.SDK INT « 
Build.VERSION CODES.JELLY BEAN MR1) { 
// If Android Beam isn't available, don't continue. 
mAndroidBeamAvailable - false; 
/* 
* Disable Android Beam file transfer features here. 
wh 


// Android Beam file transfer is available, continue 
y else { 
mNfcAdapter = NfcAdapter.getDefaultAdapter(this); 


创建 一 个 提供 文件 的 回调 函数 


一 旦 确认 了 设备 支持 Android Beam 文 件 传输 ， 那 么 可 以 添加 一 个 回调 函数 ， 当 Android Beam 
文件 传输 监测 到 用 户 希 望 向 另 一 个 支持 NFC 的 设备 发 送 文件 时 ， 系 统 就 会 调用 该 函数 。 在 该 
回调 函数 中 ， 返 回 一 个 Uri 对 象 数组 ，Android Beam 文 件 传 输 会 将 URI 对 应 的 文件 拷贝 给 要 接 
收 这 些 文件 的 设备 。 


发 送 文 件 给 其 他 设备 


要 添加 这 个 回调 函数 ， 需 要 实现 NfcAdapterCreateBeamUrisCallback 接 口 ， 和 它 的 方 
ik : createBeamUris()， 下 面 是 一 个 例子 : 


public class MainActivity extends Activity { 


// List of URIs to provide to Android Beam 
private Uri[] mFileUris - new Uri[10]; 


SUE 
* Callback that Android Beam file transfer calls to get 
* files to share 
E 
private class FileUriCallback implements 
NfcAdapter.CreateBeamUrisCallback { 
public FileUriCallback() ( 
} 
Hees 
* Create content URIs as needed to share with another device 
Uf 
@Override 
public Uri[] createBeamUris(NfcEvent event) { 
return mFileUris; 


一 旦 实现 了 这 个 接口 ， 通 过 调用 setBeamPushUrisCallback() 将 回调 函数 提供 给 Android Beam 
文件 传输 。 下 面 是 一 个 例子 : 
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public class MainActivity extends Activity { 


// Instance that returns available files from this app 
private FileUriCallback mFileUriCallback; 


@Override 
protected void onCreate(Bundle savedInstanceState) { 


// Android Beam file transfer is available, continue 


mNfcAdapter - NfcAdapter.getDefaultAdapter(this); 
/* 
* Instantiate a new FileUriCallback to handle requests for 
* URIS 
ur 
mFileUriCallback - new FileUriCallback(); 
// Set the dynamic callback for URI requests. 
mNfcAdapter.setBeamPushUrisCallback(mFileUriCallback,this); 


Note : 我 们 也 可 以 将 Uri 对 象 数组 通过 应 用 程序 的 NfcAdapter 实 例 ， 直 接 提供 给 NFC 框 
架 。 如 果 能 在 NFC 触 碰 事 件 发 生 之 前 ， 定 义 这 些 URI， 那 么 可 以 选择 使 用 这 个 方法 。 更 多 
关于 这 个 方法 的 知识 ， 请 参考 : NfcAdapter.setBeamPushUris()。 


指定 要 发 送 的 文件 


为 了 将 一 或 多 个 文件 发 送 给 其 他 支持 NFC 的 设备 ， 需 要 为 每 一 个 文件 获取 一 个 File URI (一 个 
具有 文件 格式 (file scheme) 的 URI) ， 然 后 将 它们 添加 至 一 个 Uri 对 象 数组 中 。 此 外 ， 要 传 

输 一 个 文件 ， 我 们 必须 也 拥有 该 文件 的 读 权限 。 下 例 展示 了 如 何 根据 文件 名 获取 其 File URI > 
然后 将 URI 添 加 至 数组 当中 : 


/* 
* Create a list of URIS, get a File, 
* and set its permissions 
“7 
private Uri[] mFileUris = new Uri[10]; 
String transferFile = "transferimage.jpg"; 
File extDir - getExternalFilesDir(null); 
File requestFile - new File(extDir, transferFile); 
requestFile.setReadable(true, false); 
// Get a URI for the File and add it to the list of URIs 
fileUri = Uri.fromFile(requestFile); 
if (fileUri != null) ( 
mFileUris[0] = fileUri; 
y else f 
Log.e("My Activity", "No File URI available for file."); 


接收 其 他 设备 的 文件 


编写 :jdneo - 原文 :http://developer.android.com/training/beam-files/receive-files.html 


Android Beam 文 件 传输 将 文件 拷贝 至 接收 设备 上 的 某 个 特殊 目录 。 同 时 使 用 Android Media 
Scanner 扫 描 拷 贝 的 文件 ， 并 在 MediaStore provider 中 为 媒体 文件 添加 对 应 的 条 目 记 录 。 本 课 
将 展示 当 文件 找 贝 完成 时 要 如 何 响应 ， 以 及 在 接收 设备 上 应 该 如 何 定位 找 贝 的 文件 。 


响应 请 求 并 显示 数据 


4 Android Beam 文 件 传输 将 文件 拷贝 至 接收 设备 后 ， 它 会 发 布 一 个 包含 Intent 的 通知 ， 该 
Intent 拥 有 : ACTION _VIEW， 首 个 被 传输 文件 的 MIME 类 型 ， 以 及 一 个 指向 第 一 个 文件 的 
URI。 用 户 点 击 该 通知 后 ，|ntent 会 被 发 送 至 系统 。 为 了 使 我 们 的 应 用 程序 能 够 响应 该 Intent ， 
我 们 需要 为 响应 的 Activity 所 对 应 的 <activity> 标 签 添加 一 个 <intent-filter> 标签 ， 

在 <intent-filter> 标签 中 ， 添 加 以 下 子 标签 : 


<action android:name="android.intent.action.VIEW" /> 
该 标签 用 来 匹配 从 通知 发 出 的 Intent， 这 些 Intent 具 有 ACTION _VIEW 这 一 Action ° 
«category android:name-"android.intent.category.CATEGORY DEFAULT" /> 
该 标签 用 来 匹配 不 含有 显 式 Category 的 Intent 对 象 。 
«data android:mimeType-"mime-type" /> 
该 标签 用 来 匹配 一 个 MIME 类 型 。 仅 仅 指定 那些 我 们 的 应 用 能 够 处 理 的 类 型 。 
下 例 展示 了 如 何 添加 一 个 intent filter 来 激活 我 们 的 activity : 
<activity 


android:name="com.example.android.nfctransfer.ViewActivity" 
android: label="Android Beam Viewer" > 


<intent-filter> 
<action android:name="android.intent.action.VIEW"/> 
«category android:name-"android.intent.category.DEFAULT"/» 


</intent-filter> 
</activity> 


Note : Android Beam 文 件 传输 不 是 含有 ACTION_VIEW 的 Intent 的 唯一 可 能 发 送 者 。 在 
接收 设备 上 的 其 它 应 用 也 有 可 能 会 发 送 含有 该 Action 的 intent。 我 们 马上 会 进一步 讨论 这 


一 问题 。 


请 求 文件 读 权 限 


要 读 取 Android Beam 文 件 传 输 所 拷贝 到 设备 上 的 文件 ， 需 要 请 
求 READ_EXTERNAL STORAGE 权 限 。 例 如 : 


«uses-permission android:name-"android.permission.READ EXTERNAL STORAGE" /> 


如 果 项 望 将 文件 拷贝 至 应 用 程序 自己 的 存储 区 ， 那 么 需要 的 权限 改 
为 NRITE_EXTERNAL_STORAGE ;另外 ，WRITE_EXTERNAL_STORAGE 权 限 包 含 了 
READ EXTERNAL _STORAGE 权 限 。 


Note : 对 于 Android 4.2.2 (API Level 17) 及 之 前 版 本 的 系 

% > READ EXTERNAL _STORAGE 权 限 仅 在 用 户 选择 要 读 文件 时 才 是 强制 需要 的 。 而 
在 今后 的 版 本 中 会 在 所 有 情况 下 都 需要 该 权限 。 为 保证 应 用 程序 在 未 来 的 稳定 性 ， 建 议 
在 Manifest 清 单 文件 中 声明 该 权限 。 


由 于 我 们 的 应 用 对 于 自身 的 内 部 存储 区 域 具有 控制 权 ， 因 此 当 要 将 文件 拷贝 至 应 用 程序 自身 
的 的 内 部 存储 区 域 时 ， 不 需要 声明 写 权 限 。 


获取 拷贝 文件 的 目录 


Android Beam 文 件 传 输 一 次 性 将 所 有 文件 拷贝 到 目标 设备 的 一 个 目录 中 ，Android Beam x fF 
传输 通知 所 发 出 的 Intent 中 含有 指向 了 第 一 个 被 传输 的 文件 的 URI。 然 而 ， 我 们 的 应 用 程序 也 
有 可 能 接收 到 除了 Android Beam 文 件 传输 之 外 的 某 个 来 源 所 发 出 的 含有 ACTION_VIEW 这 一 
Action 的 Intent。 为 了 明确 应 该 如 何 处 理 接收 的 Intent， 我 们 要 检查 它 的 Scheme 和 Authority。 


可 以 调用 Uri.getScheme() 获 得 URI 的 Scheme， 下 例 展 示 了 如 何 确定 Scheme 并 对 URI 进 行 相 
应 的 处 理 : 


public 


class MainActivity extends Activity ( 


// A File object containing the path to the transferred files 


private File mParentPath; 


// Incoming Intent 


private Intent mIntent; 


ax 


* 


* 


* 


ey 


Called from onNewIntent() for a SINGLE TOP Activity 
or onCreate() for a new Activity. For onNewIntent(), 
remember to call setIntent() to store the most 
current Intent 


private void handleViewIntent() { 


// Get the intent action 
mIntent = getIntent(); 
String action = mIntent.getAction(); 
TOS 
* For ACTION_VIEW, the Activity is being asked to display data. 
"Get the URI. 
sp 
if (TextUtils.equals(action, Intent.ACTION VIEW)) { 
// Get the URI from the Intent 
Uri beamUri = mIntent.getData(); 
yu 
* Test for the type of URI, by getting its scheme value 
he 
if (TextUtils.equals(beamUri.getScheme(), "file")) ( 
mParentPath - handleFileUri(beamUri); 
) eise if (TextUtils.equals( 
beamUri.getScheme(), "content")) { 
mParentPath = handleContentUri(beamUri); 


从 File URI 中 获取 目录 


如 果 接 收 的 Intent 包 含 一 个 File URI， 则 该 URI 包 含 了 一 个 文件 的 绝对 文件 名 ， 它 包括 了 完整 的 
路 径 和 文件 名 。 对 Android Beam 文 件 传 输 来 说 ， 目 录 路 径 指向 了 其 它 被 传输 文件 的 位 置 (如 
果 有 其 它 传 输 文件 的 话 ) ， 要 获得 该 目录 路 径 ， 需 要 取得 URI 的 路 径 部 分 (URI 中 除去 file:" 前 
级 的 部 分 ) ， 根 据 路 径 创 建 一 个 File 对 象 ， 然 后 获取 这 个 File 的 父 目录 : 


public String handleFileUri(Uri beamUri) { 
// Get the path part of the URI 
String fileName - beamUri.getPath(); 
// Create a File object for this filename 
File copiedFile - new File(fileName); 
// Get a string containing the file's parent directory 
return copiedFile.getParent(); 


JA. Content URI 获 取 目 录 


如 果 接 收 的 Intent 包 含 一 个 Content URI， 这 个 URI 可 能 指向 的 是 存储 于 MediaStore Content 
Provider 的 目录 和 文件 名 。 我 们 可 以 通过 检测 URI 的 Authority 值 来 判断 它 是 否 是 来 自 于 
MediaStore 的 Content URI。 一 个 MediaStore 的 Content URI 可 能 来 自 Android Beam 文 件 传输 
也 可 能 来 自 其 它 应 用 程序 ， 但 不 管 怎么 样 ， 我 们 都 能 根据 该 Content URI 获 得 一 个 目录 路 径 和 
文件 名 。 


我 们 也 可 以 接收 一 个 含有 ACTION_VIEW 这 一 Action 的 Intent， 它 包含 的 Content URI 针 对 于 
Content Provider ;而 不 是 MediaStore， 这 种 情况 下 ， 该 Content URI 不 包含 MediaStore 的 
Authority， 且 这 个 URI 一 般 不 指向 一 个 目录 。 


Note : 对 于 Android Beam 文 件 传输 ， 接 收 在 含有 ACTION _VIEW 的 Intent 中 的 Content 
URI 时 ， 若 第 一 个 接收 的 文件 MIME 类 型 为 “audio/”，“image/" 或 者 “video/*”，Android 
Beam 文 件 传 输 会 在 它 存储 传输 文件 的 目录 内 运行 Media Scanner， 以 此 为 媒体 文件 添加 
索引 。 同 时 Media Scanner 将 结果 写 入 MediaStore 的 Content Provider， 之 后 它 将 第 一 个 
文件 的 Content URI 回 递 给 Android Beam 文 件 传 输 。 这 个 Content URI 就 是 我 们 在 通知 
Intent 中 所 接收 到 的 。 要 获得 第 一 个 文件 的 目录 ， 需 要 使 用 该 Content URI 从 MediaStore 
中 获取 它 。 


确定 Content Provider 


为 了 确定 是 否 能 从 Content URI 中 获取 文件 目录 ， 可 以 通过 调用 Uri.getAuthority() 获 取 URI 的 
Authority， 以 此 确定 与 该 URI 相 关联 的 Content Provider。 其 结果 有 两 个 可 能 的 值 : 


MediaStore.AUTHORITY 


表明 该 URI 关 联 了 被 MediaStore 记 录 的 一 个 文件 或 者 多 个 文件 。 可 以 从 MediaStore 中 获取 文 
件 的 全 名 ， 目 录 名 就 自然 可 以 从 文件 全 名 中 获取 。 


其 他 值 


来 自 其 他 Content Provider 的 Content URI。 可 以 显示 与 该 Content URI 相 关联 的 数据 ， 但 是 不 
尝试 去 获取 文件 目录 。 


要 从 MediaStore 的 Content URI 中 获取 目录 ， 我 们 需要 执行 一 个 查询 操作 ， 它 将 Uri 参 数 指定 为 
收 到 的 ContentURI， 将 MediaColumns.DATA 列 作为 投影 (Projection ) 。 返 回 的 Cursor 对 象 
包含 了 URI 所 代表 的 文件 的 完整 路 径 和 文件 名 。 该 目录 路 径 下 还 包含 了 由 Android Beam 文 件 
传输 传送 到 该 设备 上 的 其 它 文件 。 


下 面 的 代码 展示 了 如 何 测试 Content URI 的 Authority， 并 获取 传输 文件 的 路 径 和 文件 名 : 


public String handleContentUri(Uri beamUri) { 
// Position of the filename in the query Cursor 
int filenameIndex; 
// File object for the filename 
File copiedFile; 
// The filename stored in MediaStore 
String fileName; 
// Test the authority of the URI 
if (!TextUtils.equals(beamUri.getAuthority(), MediaStore.AUTHORITY)) { 





/* 
* Handle content URIs for other content providers 
uf 

// For a MediaStore content URI 

} else { 


// Get the column that contains the file name 
String[] projection = { MediaStore.MediaColumns.DATA }; 
Cursor pathCursor = 
getContentResolver().query(beamUri, projection, 
UHL (all gU LO s 
// Check for a valid cursor 
if (pathCursor !- null && 
pathCursor.moveToFirst()) { 
// Get the column index in the Cursor 
filenameIndex = pathCursor.getColumnIndex( 
MediaStore.MediaColumns.DATA); 
// Get the full file name including path 
fileName = pathCursor.getString(filenameIndex); 
// Create a File object for the filename 
copiedFile - new File(fileName); 
// Return the parent directory of the file 
return new File(copiedFile.getParent()); 
) else { 
// The query didn't work; return null 
return null; 


$ £ X TJ. Content Provider 获 取 数 据 的 知识 ， 请 参考 : Retrieving Data from the Provider » 


接收 其 他 设备 的 文件 
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Android 多 媒体 


编写 :kesenhoo - 原文 :http://developer.android.com/training/building-multimedia.html 
下 面 的 这 些 课程 会 教 你 如 何 创 建 更 加 符合 用 户 期 待 的 富 媒体 的 应 用 。 
管理 音频 播放 (Managing Audio Playback) 


如 何 响 应 音频 硬件 按钮 的 点 击 事件 ， 在 播放 音频 的 时 候 请 求 audio focus， 以 及 如 何 正确 的 响 
应 audio focus 的 改变 。 


拍照 (Capturing Photos) 
如 何 利用 以 及 存在 的 相机 应 用 进行 拍照 ， 如 何 直接 控制 相机 硬件 实现 你 自己 的 相机 应 用 。 


打印 (Printing Content) 


如 何 打印 照片 ，HTML 文 档 ， 自 定义 的 文档 。 


Co 


管理 音频 播放 


编写 :kesenhoo - 原文 :http://developer.android.com/training/managing-audio/index.html 


如 果 我 们 的 应 用 能 够 播放 音频 ， 那 么 让 用 户 能 够 以 自己 预期 的 方式 控制 音频 是 很 重要 的 。 为 
了 保证 良好 的 用 户 体验 ， 我 们 应 该 让 应 用 能 够 管理 当前 的 音频 焦点 ， 因 为 这 样 才 能 确保 多 个 
应 用 不 会 在 同一 时 刻 一 起 播放 音频 。 

在 学 习 本 系列 课程 中 ， 我 们 将 会 创建 可 以 对 音量 按钮 进行 响应 的 应 用 ， 该 应 用 会 在 播放 音频 
的 时 候 请 求 获取 音频 焦点 ， 并 且 在 当前 音频 焦点 被 系统 或 其 他 应 用 所 改变 的 时 候 ， 做 出 正确 
的 响应 。 


Lessons 


e 控制 音量 与 音频 播放 (Controlling Your App's Volume and Playback) 


学 习 如 何 确保 用 户 能 通过 硬件 或 软件 音量 控制 器 调节 应 用 的 音量 【通常 这 些 控制 器 上 还 
具有 播放 、 停 止 、 暂 停 、 跳 过 以 及 回放 等 功能 按键 ) 。 


e 管理 音频 焦点 (Managing Audio Focus) 


由 于 可 能 会 有 多 个 应 用 具有 播放 音频 的 功能 ， 考 虑 他 们 如 何 交 互 非常 重要 。 为 了 防止 多 
个 音乐 应 用 同时 播放 音频 ，Android 使 用 音频 焦点 (Audio Focus) 来 控制 音频 的 播放 。 
在 这 节 课 中 可 以 学 习 如 何 请 求 音频 焦点 ， 监 听 音 频 焦 点 的 丢失 ， 以 及 在 这 种 情况 发 生 时 
应 该 如 何 做 出 响应 。 


e 兼容 音频 输出 设备 (Dealing with Audio Output Hardware) 


音频 有 多 种 输出 设备 ， 在 这 节 课 中 可 以 学 习 如 何 找 出 播放 音频 的 设备 ， 以 及 处 理 播放 时 
耳机 被 拔 出 的 情况 。 


控制 音量 与 音频 播放 


编写 :kesenhoo - 原文 :http://developer.android.com/training/managing-audio/volume- 
playback.html 


良好 的 用 户 体验 应 该 是 可 预期 且 可 控 的 。 如 果 我 们 的 应 用 可 以 播放 音频 ， 那 么 显然 我 们 需要 
做 到 能 够 通过 硬件 按钮 ， 软 件 按钮 ， 蓝 牙 耳 麦 等 来 控 外 House E 
的 音频 流 进行 播放 (Play) > ak (Stop) > 444 (Pause) ， 跳 过 (Skip) ， 以 及 回放 
(Previous) 等 动作 ， 并 且 并 确保 其 正确 性 。 


鉴别 使 用 的 是 哪个 首 频 流 (Identify Which Audio 
Stream to Use) 


为 了 创建 一 个 良好 的 音频 体验 ， 我 们 首先 需要 知道 应 用 会 使 用 到 哪些 音频 流 。Android 为 播放 

音乐 ， 闹 铃 ， 通 知 铃 ， 来 电 声 音 ， 系 统 声音 ， 打 电话 声音 与 拨号 声音 分 别 维护 了 一 个 独立 的 

音频 流 。 这 样 做 的 主要 目的 是 让 用 户 能 够 单独 地 控制 不 同 的 种 类 的 音频 。 上 述 音 频 种 类 中 ， 

A n a 。 例 如 ， 除 非 你 的 应 用 需要 做 替换 闹钟 的 铃声 的 操作 ， 不 然 的 话 你 只 
824 HSTREAM MUSIC 48x 4p 89 Hp 398. 9 


使 用 硬件 音量 键 来 控制 应 用 的 音量 (Use Hardware 
Volume Keys to Control Your App's Audio 
Volume) 


默认 情况 下 ， 按 下 音量 控制 键 会 调节 当前 被 激活 的 音频 流 ， 如 果 我 们 的 应 用 当前 没有 播放 任 
何 声音 ， 那 么 按 下 音量 键 会 调节 响 铃 的 音量 。 对 于 游戏 或 者 音乐 播放 器 而 言 ， 即 使 是 在 歌曲 
之 间 无 声音 的 状态 ， 或 是 当前 游戏 处 于 无 声 TEN ， 用户 按 下 音量 键 的 操作 通常 都 意味 着 他 
们 希望 调节 游戏 或 者 音乐 的 音量 。 你 可 能 希望 通过 监听 音量 键 被 按 下 的 事件 ， 来 调节 音频 流 
的 音量 。 其 实 我 们 不 必 这 样 做 。Android 提 供 了 setVolumeControlStream() 方 法 来 直接 控制 指 
定 的 音频 流 。 在 鉴别 出 应 用 会 使 用 哪个 音频 流 之 后 ， 我 们 需要 在 应 用 生命 周期 的 早期 阶段 调 
用 该 方法 ， 因 为 该 方法 只 需要 在 Activity 整 个 生命 周期 es ， 通常 ， 我 们 可 以 在 负责 控 
制 多 媒体 的 Activity 或 者 Fragment 的 oncreate() 方法 中 调用 它 。 这 样 能 确保 不 管 应 用 当前 是 否 
可 见 ， 音 频 控 制 的 功能 都 能 符合 用 户 的 预期 。 


setVolumeControlStream(AudioManager.STREAM MUSIC); 


自 此 之 后 ， 不 管 目标 Activity 或 Fragment 是 否 可 见 ， 按 下 设备 的 音量 键 都 能 够 影响 我 们 指定 的 
音频 流 ( 在 这 个 例子 中 ， 音 频 流 是 "music") 。 


使 用 硬件 的 播放 控制 按键 来 控制 应 用 的 首 频 播放 
(Use Hardware Playback Control Keys to 
Control Your App's Audio Playback) 


许多 线 控 或 者 无 线 耳机 都 会 有 许多 媒体 播放 控制 按钮 ， 例 如 : 播放 ， 停 止 ， 暂 停 ， 跳 过 ， 以 
及 回放 等 。 无 论 用 户 按 下 设备 上 任意 一 个 控制 按钮 ， 系 统 都 会 广播 一 个 带 

有 ACTION_MEDIA_BUTTON 的 Intent。 为 了 正确 地 响应 这 些 操作 ， 需 要 在 Manifest 文 件 中 注 
册 一 个 针对 于 该 Action 的 BroadcastReceiver， 如 下 所 示 : 


«receiver android:name=".RemoteControlReceiver"> 
<intent-filter> 
<action android:name="android.intent.action.MEDIA BUTTON" /> 
</intent-filter> 
</receiver> 


在 Receiver 的 实现 中 ， 需 要 判断 这 个 广播 来 自 于 哪 一 个 按钮 ，Intent 通 过 
EXTRA_KEY_EVENT 这 一 Key 包 含 了 该 信 息 ， 另 外 ， KeyEvent 类 包含 了 一 系列 诸 
如 KEYCODE MEDIA * 的 静态 变量 来 表示 不 同 的 媒体 按钮 ， 例 如 
KEYCODE MEDIA PLAY PAUSE 4 KEYCODE MEDIA NEXT ° 


public class RemoteControlReceiver extends BroadcastReceiver { 
@Override 
public void onReceive(Context context, Intent intent) { 
if (Intent.ACTION MEDIA BUTTON.equals(intent.getAction())) { 
KeyEvent event - (KeyEvent)intent.getParcelableExtra(Intent.EXTRA KEY EVEN 
T); 
if (KeyEvent.KEYCODE MEDIA PLAY == event.getKeyCode()) ( 
// Handle key press 


j 


为 可 能 会 有 多 个 程序 在 监听 与 媒体 按钮 相关 的 事件 ， 所 以 我 们 必须 在 代码 中 控制 应 用 接收 
相关 事件 的 时 机 。 下 面 的 例子 显示 了 如 何 使 用 AudioManager 来 为 我 们 的 应 用 注册 监听 与 取消 
监听 媒体 按钮 事件 ， 当 Receiver 被 注册 上 时 ， 它 将 是 唯一 一 个 能 够 响应 媒体 按钮 广播 的 


Receiver ° 


AudioManager am = mContext.getSystemService(Context.AUDIO SERVICE); 


// Start listening for button presses 
am.registerMediaButtonEventReceiver(RemoteControlReceiver); 


// Stop listening for button presses 
am.unregisterMediaButtonEventReceiver(RemoteControlReceiver); 


通常 ， 应 用 需要 在 他 们 失去 焦点 或 者 不 可 见 的 时 候 (比如 在 onStop() 方 法 里 面 ) 取消 注册 监 
听 。 但 是 对 于 媒体 播放 应 用 来 说 并 没有 那么 简单 ， 实 际 上 ， 在 应 用 不 可 见 (不 能 通过 可 见 的 
Ul 控件 进行 控制 ) 的 时 候 ， 仍 然 能 够 响应 媒体 播放 按钮 事件 是 极其 重要 的 。 为 了 实现 这 一 
点 ， 有 一 个 更 好 的 方法 ， 我 们 可 以 在 程序 获取 与 失去 音频 焦点 的 时 候 注册 与 取消 对 音频 按钮 
事件 的 监听 。 这 个 内 容 会 在 后 面 的 课程 中 详细 讲解 。 


Q 


Kj 5 : 
cL AE 
ra” E E 频 ANSN 点 
编写 :kesenhoo - 原文 :http://developer.android.com/training/managing-audio/audio- 


focus.html 


由 于 可 能 会 有 多 个 应 用 可 以 播放 音频 ， 所 以 我 们 应 当 考 虑 一 下 他 们 应 该 如 何 交 互 。 为 了 防止 
多 个 音乐 播放 应 用 同时 播放 音频 ，Android 使 用 音频 焦点 (Audio Focus) 来 控制 音频 的 播放 
一 一 即 只 有 获取 到 音频 焦点 的 应 用 才能 够 播放 音频 。 


在 我 们 的 应 用 开始 播放 音频 之 前 ， 它 需要 先 请 求 音频 焦点 ， 然 后 再 获取 到 音频 焦点 。 另 外 ， 
它 还 需要 知道 如 何 监听 失去 音频 焦点 的 事件 并 对 此 做 出 合适 的 响应 。 


请 求 获 取 音 频 焦 点 (Request the Audio Focus) 


在 我 们 的 应 用 开始 播放 音频 之 前 ， 它 需要 获取 将 要 使 用 的 音频 流 的 音频 焦点 。 通 过 使 
用 requestAudioFocus() 方法 可 以 获取 我 们 希望 得 到 的 音频 流 焦点 。 如 果 请 求 成 功 ， 该 方法 会 
返回 AUDIOFOCUS REQUEST GRANTED ° 


另外 我 们 必须 指定 正在 使 用 的 音频 流 ， 而 且 需 要 确定 所 请 求 的 音频 焦点 是 短暂 的 
(Transient) 还 是 永久 的 (Permanent) 。 


e 短暂 的 焦点 锁定 : 当 计 划 播 放 一 个 短暂 的 音频 时 使 用 (比如 播放 导航 指示 ) 。 
e 永久 的 焦点 锁定 : 当 计 划 播 放 一 个 较 长 但 时 长 可 预期 的 音频 时 使 用 (比如 播放 音乐 ) 。 


下 面 的 代码 片段 是 一 个 在 播放 音乐 时 请 求 永久 音频 焦点 的 例子 ， 我 们 必须 在 开始 播放 之 前 立 
即 请 求 音频 焦点 ， 比 如 在 用 户 点 击 播放 或 者 游戏 中 下 一 关 的 背景 音乐 开始 前 。 


AudioManager am = mContext.getSystemService(Context.AUDIO SERVICE); 


// Request audio focus for playback 

int result - am.requestAudioFocus(afChangeListener, 
// Use the music stream. 
AudioManager.STREAM MUSIC, 
// Request permanent focus. 
AudioManager.AUDIOFOCUS GAIN); 


if (result == AudioManager.AUDIOFOCUS REQUEST GRANTED) { 
am.registerMediaButtonEventReceiver(RemoteControlReceiver); 
// Start playback. 


一 旦 结束 了 播放 ， 需 要 确保 调用 了 abandonAudioFocus() 方 法 。 这 样 相 当 于 告知 系统 我 们 不 再 
需要 获取 焦点 并 且 注 销 所 关联 的 AudioManager.OnAudioFocusChangeListener 监 听 器 。 对 于 
另 一 种 释放 短暂 音频 焦点 的 情况 ， 这 会 允许 任何 被 我 们 打 断 的 应 用 可 以 继续 播放 。 


// Abandon audio focus when playback complete 
am.abandonAudioFocus(afChangeListener); 


当 请 求 短 暂 音 频 焦点 的 时 候 ， 我 们 可 以 选择 是 否 开 局 "Ducking”。 通 常情 况 下 ， 一 个 应 用 在 失 
去 音频 焦点 时 会 立即 关闭 它 的 播放 声音 。 如 果 我 们 选择 在 请 求 短 暂 音 频 焦点 的 时 候 开 居 了 
Ducking， 那 意味 着 其 它 应 用 可 以 继续 播放 ， 仅 仅 是 在 这 一 刻 降 低 自己 的 音量 ， 直 到 重新 获取 
到 音频 焦点 后 恢复 正常 音量 (译注 : 也 就 是 说 ， 不 用 理会 这 个 短暂 焦点 的 请 求 ， 这 并 不 会 打 
断 目前 正在 播放 的 音频 。 比 如 在 播放 音乐 的 时 候 突然 出 现 一 个 短暂 的 短信 提示 声音 ， 此 时 仅 
仅 是 把 歌曲 的 音量 暂时 调 低 ， 使 得 用 户 能 够 听 到 短信 提示 声 ， 在 此 之 后 便 立 马 恢复 正常 播 
a) 。 


// Request audio focus for playback 

int result = am.requestAudioFocus(afChangeListener, 
// Use the music stream. 
AudioManager.STREAM MUSIC, 
// Request permanent focus. 
AudioManager.AUDIOFOCUS GAIN TRANSIENT MAY DUCK); 


if (result == AudioManager.AUDIOFOCUS REQUEST GRANTED) { 
// Start playback. 


} 


Ducking 对 于 那些 间歇 性 使 用 音频 焦点 的 应 用 来 说 特别 合适 ， 比 如 语音 导航 。 


如 果 有 另 一 个 应 用 像 上 述 那样 请 求 音频 焦点 ， 它 所 请 求 的 永久 音频 焦点 或 者 短暂 音频 焦点 
(支持 Ducking 或 不 支持 Ducking ) ， 都 会 被 你 在 请 求 获取 音频 焦点 时 所 注册 的 监听 器 接收 
到 o 


处 理 失去 音频 焦点 (Handle the Loss of Audio 
Focus) 

如 果 应 用 A 请 求 获取 了 音频 焦点 ， 那 么 在 应 用 B 请 求 获取 音频 焦点 的 时 候 ，A 获 取 到 的 焦点 就 
会 失去 。 如 何 响应 失去 焦点 事件 ， 取 决 于 失去 焦点 的 方式 。 


在 音频 焦点 的 监听 器 里 面 ， 当 接受 到 描述 焦点 改变 的 事件 时 会 触发 onAudioFocusChange() 回 
调 方法 。 如 之 前 提 到 的 ， 获 取 焦 点 有 三 种 类 型 ， 我 们 同样 会 有 三 种 失去 焦点 的 类 型 : 永久 失 
去 ， 短 暂 失 去 ， 人 允许 Ducking 的 短暂 失去 。 


e 失去 短暂 焦点 : 通常 在 失去 短暂 焦点 的 情况 下 ， 我 们 会 暂停 当前 音频 的 播放 或 者 降低 音 
量 ， 同 时 需要 准备 在 重新 获取 到 焦点 之 后 恢复 播放 。 


e 失去 永久 焦点 : 假设 另外 一 个 应 用 开始 播放 音乐 ， 那 么 我 们 的 应 用 就 应 该 有 效 地 将 自己 
停止 。 在 实际 场景 当中 ， 这 意味 着 停止 播放 ， 移 除 媒体 按钮 监听 ， 允 许 新 的 音频 播放 器 
可 以 唯一 地 监听 那些 按钮 事件 ， 并 且 放 弃 自 己 的 音频 焦点 。 此 时 ， 如 果 想 要 恢复 自己 的 
音频 播放 ， 我 们 需要 等 待 某 种 特定 用 户 行为 发 生 (例如 按 下 了 我 们 应 用 当中 的 播放 按 
41) » 


在 下 面 的 代码 片段 当中 ， 如 果 焦 点 的 失去 是 短暂 型 的 ， 我 们 将 音频 播放 对 象 暂 停 ， 并 在 重新 
获取 到 焦点 后 进行 恢复 。 如 果 是 永久 型 的 焦点 失去 事件 ， 那 么 我 们 的 媒体 按钮 监听 器 会 被 注 
销 ， 并 且 不 再 监听 音频 焦点 的 改变 。 


OnAudioFocusChangeListener afChangeListener = new OnAudioFocusChangeListener() { 
public void onAudioFocusChange(int focusChange) { 

if (focusChange == AUDIOFOCUS_LOSS_TRANSIENT 
// Pause playback 

} else if (focusChange == AudioManager.AUDIOFOCUS GAIN) { 
// Resume playback 

) else if (focusChange == AudioManager.AUDIOFOCUS LOSS) { 
am.unregisterMediaButtonEventReceiver(RemoteControlReceiver); 
am.abandonAudioFocus(afChangeListener); 
// Stop playback 


在 上 面 失去 短暂 焦点 的 例子 中 ， 如 果 人 允许 Ducking， 那 么 除了 暂停 当前 的 播放 之 外 ， 我 们 还 可 
以 选择 使 用 “Ducking”。 


Duck! 
在 使 用 Ducking 时 ， 正 常 播放 的 歌曲 会 降低 音量 来 凸显 这 个 短暂 的 音频 声音 ， 这 样 既 让 这 个 短 
暂 的 声音 比较 突出 ， 又 不 至 于 打 断 正常 的 声音 。 


下 面 的 代码 片段 让 我 们 的 播放 器 在 暂时 失去 音频 焦点 时 降低 音量 ， 并 在 重新 获得 音频 焦点 之 
后 恢复 原来 音量 。 


OnAudioFocusChangeListener afChangeListener = new OnAudioFocusChangeListener() { 
public void onAudioFocusChange(int focusChange) { 
if (focusChange == AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK) { 
// Lower the volume 
} else if (focusChange == AudioManager.AUDIOFOCUS GAIN) { 
// Raise it back to normal 


HN 


音频 焦点 的 失去 是 我 们 需要 响应 的 最 重要 的 事件 广播 之 一 ， 但 除 此 之 外 还 有 很 多 其 他 重要 的 


广播 需要 我 们 正确 地 做 出 响应 。 系 统 会 广播 一 系列 的 Intent 来 向 你 告知 用 户 在 使 用 音频 过 程 当 
中 的 各 种 变化 。 下 节 课 会 演示 如 何 监听 这 些 广 播 并 提升 用 户 的 整体 体验 。 


编写 :kesenhoo - /$ X :http://developer.android.com/training/managing-audio/audio- 


output.html 


当 用 户 想 要 通过 Android 设 备 欣 赏 音乐 的 时 候 ， 他 可 以 有 多 种 选择 ， 大 多 数 设 备 拥有 内 置 的 扬 
声 器 ， 有 线 耳机 ， 也 有 其 它 很 多 设备 支持 蓝牙 连接 ， 有 些 甚 至 还 支持 A2DP 蓝 牙 音 频传 输 模 型 
协定 。 (译注 : A2DP 全 名 是 Advanced Audio Distribution Profile 蓝牙 音频 传输 模型 协定 ! 
的 芯片 来 堆栈 数据 ， 达 到 声音 的 高 清晰 度 。 有 A2DP 的 耳机 就 是 蓝 
立体 声 耳 机 。 声 音 能 达到 44.1kHz， 一 般 的 耳机 只 能 达到 8kHz。 如 果 手 机 支持 蓝牙 ， 只 要 装 
载 A2DP 协 议 ， ee 。 还 有 消费 者 看 到 技术 参数 提 到 蓝牙 V1.0 V1.1 V1.2 
V2.0 - 这 些 是 指 蓝牙 的 技术 版 本 ， 是 指 通 过 蓝牙 传输 的 速度 ， 他 们 是 否 支 持 A2DP 具 体 要 看 蓝 
牙 产 品 制 造 商 是 否 使 用 这 个 技术 。 来 自 百 度 百科 ) 


检测 目前 正在 使 用 的 硬件 设备 (Check What 
Hardware is Being Used) 


使 用 不 同 的 硬件 播放 声 证 


音 会 影响 到 应 用 的 行为 。 可 以 使 用 AudioManager 来 查询 当前 音频 是 输 
出 到 扬声器 ， 有 线 耳 机 还 是 蓝 


蓝牙 上 ， 如 下 所 示 : 


If (isBluetoothA2dpOn()) { 
// Adjust output for Bluetooth. 


) else if (isSpeakerphoneOn()) { 


// Adjust output for Speakerphone 
} else if orm t 
// Adjust output for he 
} else { 
// If audio plays and noone can hear it, is it still playing? 


} 


处 理 音频 输出 设备 的 改变 (Handle Changes in the 
Audio Output Hardware) 


当 有 线 耳 机 被 拔 出 e 监 牙 设备 断 开 连接 的 时 候 ， 音 频 流 会 自动 输出 到 内 置 的 扬声器 上 。 假 
设 播放 声音 很 大 ， 这 个 时 候 突 然 转 到 扬声器 播放 会 显得 非常 噶 杂 。 


幸运 的 是 ， 系 统 会 在 这 种 情况 下 广播 带 有 ACTION_AUDIO_BECOMING _NOISY 的 Intent。 无 
论 何 时 播放 音频 ， 我 们 都 应 该 注册 一 个 BroadcastReceiver 来 监听 这 个 Intent。 在 使 用 音乐 播 
放 器 时 ， 用 户 通 常会 希望 此 时 能 够 暂停 当前 歌曲 的 播放 。 而 在 游戏 当中 ， 用 户 通常 会 希望 可 


以 减低 音量 。 


private class NoisyAudioStreamReceiver extends BroadcastReceiver { 
@Override 
public void onReceive(Context context, Intent intent) { 
if (AudioManager.ACTION AUDIO BECOMING NOISY.equals(intent.getAction())) ( 
// Pause the playback 


private IntentFilter intentFilter - new IntentFilter(AudioManager.ACTION AUDIO BECOMIN 
G NOISY); 


private void startPlayback() { 


registerReceiver(myNoisyAudioStreamReceiver(), intentFilter); 


private void stopPlayback() { 
unregisterReceiver(myNoisyAudioStreamReceiver); 


拍照 


编写 :kesenhoo - 原文 :http://developer.android.com/training/camera/index.html 


在 多 媒体 技术 还 未 流行 之 时 ， 我 们 的 世界 并 不 像 现 在 这 样 多 奖 多 彩 。 还 记得 Gopher 吗 ? 

(Gopher 是 计算 机 上 的 一 个 工具 软件 ， 是 /nternet 提 供 的 一 种 由 菜单 式 驱 动 的 信息 查询 工具 ， 
采用 客户 机 /服务 器 模式 ) 。 如 果 我 们 希望 将 我 们 的 应 用 变 成 用 户 生活 的 一 部 分 ， 那 么 我 们 应 
该 给 用 户 提 供 一 种 方式 ， 让 他 们 可 以 将 自己 的 生活 融入 到 我 们 的 应 用 中 来 。 通 过 相机 ， 我 们 
的 应 用 可 以 让 用 户 扩展 他 们 所 看 到 的 事物 : 生成 唯一 的 头像 ， 通 过 相机 玩 寻 找 僵尸 的 交互 性 
游戏 ， 亦 或 者 是 分 享 他 们 的 茶 些 经 历 。 


这 一 章节 ， 我 们 会 学 习 如 何 简单 地 借助 于 已 经 存在 的 相机 应 用 ， 完 成 一 些 特定 的 功能 。 在 后 
面 的 课程 中 ， 我 们 还 会 更 加 深入 地 学 习 如 何 直接 控制 相机 硬件 。 


样 例 代码 


PhotolntentActivity.zip 


Lessons 


o 轻松 拍摄 照片 

用 仅仅 几 行 代码 调用 其 他 应 用 拍照 。 
e 轻松 录制 视频 

用 仅仅 几 行 代码 调用 其 他 应 用 录像 。 
e 控制 相机 


直接 控制 相机 硬件 ， 实 现 你 自己 的 相机 应 用 。 


轻松 拍摄 照片 


编写 :kesenhoo - 原文 :http://developer.android.com/training/camera/photobasics.html 
这 节 课 将 讲解 如 何 使 用 已 有 的 相机 应 用 拍摄 照片 。 


假设 我 们 正在 实现 一 个 基于 人 群 的 气象 服务 ， 通 过 应 用 客户 端 NE PUE cdi wet 
可 以 组 成 全 球 气 象 图 。 整 合 图 片 只 是 应 用 的 一 小 部 分 ， 我 们 想 要 通过 最 简单 的 方式 获取 图 
片 ， 而 不 是 重新 设计 并 实现 一 个 具有 相机 功能 的 组 件 。 幸 运 的 是 ， 通 常 来 说 ， 大 多 数 Android 
设备 都 已 经 安装 了 至 少 一 款 相 机 程序 。 在 这 节 课 中 ， 我 们 会 学 习 如 何 利 用 已 有 的 相机 应 用 拍 
摄 照片 。 


青 求 使 用 相机 权限 


如 果 拍 照 是 应 用 的 必要 功能 ， 那 么 应 该 令 它 在 Google Bi A iced 为 了 让 
用 户 知 道 我 们 的 应 用 需要 依赖 相机 ， 在 Manifest 清 单 文 件 中 添加 <uses-feature> 标签 


<manifest ... > 
<uses-feature android:name="android.hardware.camera" 
android:required-"true" /» 


«/manifest» 


如 果 我 们 的 应 用 使 用 相机 ， 但 相机 并 不 是 应 用 的 正常 运行 所 必 不 可 少 的 组 件 ， 可 以 

将 android:required 设置 为 "false" 。 这 样 的 话 ， Google Play 也 会 允许 没有 相机 的 设备 下 载 
该 应 用 。 当 然 我 们 有 必要 在 使 用 相机 之 前 通过 调 

用 hasSystemFeature(PackageManagerFEATURE_CAMERA) 方 法 来 检查 设备 上 是 否 有 相 
机 。 如 果 没 有 ， 我 们 应 该 禁用 和 相机 相关 的 功能 


使 用 相机 应 用 程序 进行 拍照 


利用 一 个 描述 了 执行 目的 Intent 对 象 ，Android 可 以 将 某 些 执行 任务 委托 给 其 他 应 用 。 整 个 过 
程 包 含 三 部 分 : Intent 本 身 ， 一 个 函数 调用 来 启动 外 部 的 Activity， 当 焦点 返回 到 我 们 的 
Activity 时 ， 处 理 返回 图 像 数据 的 代码 。 


下 面 的 函数 通过 发 送 一 个 Intent 来 捕获 照片 : 


static final int REQUEST IMAGE CAPTURE = 1; 


private void dispatchTakePictureIntent() { 
Intent takePictureIntent - new Intent(MediaStore.ACTION IMAGE CAPTURE); 
if (takePictureIntent.resolveActivity(getPackageManager()) != null) ( 
startActivityForResult(takePictureIntent, REQUEST IMAGE CAPTURE); 


注意 在 调用 startActivityForResult() 方 法 之 前 ， 先 调用 resolveActivity()， 这 个 方法 会 返回 能 处 
理 该 Intent 的 第 一 个 Activity (译注 : 即 检查 有 没有 能 处 理 这 个 Intent 的 Activity) 。 执 行 这 个 检 
查 非常 重要 ， 因 为 如 果 在 调用 startActivityForResult() 时 ， 没 有 应 用 能 处 理 你 的 Intent， 应 用 将 
会 前 演 。 所 以 只 要 返回 结果 不 为 null， 使 用 该 Intent 就 是 安全 的 。 


说 


获取 缩 略 图 


拍摄 照片 并 不 是 应 用 的 最 终 目 的 ， 我 们 还 想 要 从 相机 应 用 那里 取 回 拍摄 的 照片 ， 并 对 它 执行 
某 些 操作 。 


Android 的 相机 应 用 会 把 拍 好 的 照片 编码 为 缩小 的 Bitmap， 使 用 extra value 的 方式 添加 到 返回 
的 Intent 当 中 ， 并 传送 给 onActivityResult()， 对 应 的 Key 为 "data" 。 下 面 的 代码 展示 的 是 如 何 
获取 这 一 图 片 并 显示 在 ImageView 上 。 


@Override 
protected void onActivityResult(int requestCode, int resultCode, Intent data) { 
if (requestCode == REQUEST IMAGE CAPTURE && resultCode == RESULT OK) ( 
Bundle extras - data.getExtras(); 
Bitmap imageBitmap = (Bitmap) extras.get("data"); 
mImageView.setImageBitmap(imageBitmap); 


Note: 这 张 从 "data" 中 取出 的 缩 略 图 适用 于 作为 图 标 ， 但 其 他 作用 会 比较 有 限 。 而 处 理 
一 张 全 尺寸 图 片 需要 做 更 多 的 工作 。 


保存 全 尺寸 照片 


如 果 我 们 提供 了 一 个 File 对 象 给 Android 的 相机 程序 ， 它 会 保存 这 张 全 尺寸 照片 到 给 定 的 路 径 
下 。 另 外 ， 我 们 必须 提供 存储 图 片 所 需要 的 含有 后 级 名 形式 的 文件 名 。 


一 般 而 言 ， 用 户 使 用 设备 相机 所 拍摄 的 任何 照片 都 应 该 被 存放 在 设备 的 公共 外 部 存储 中 ， 这 
样 它们 就 能 被 所 有 的 应 用 访问 。 将 DIRECTORY_ PICTURES 作为 参数 ， 传 递 给 
getExternalStoragePublicDirectory() 方 法 ， 可 以 返回 适用 于 存储 公共 图 片 的 目录 。 由 于 该 方 
法 提供 的 目录 被 所 有 应 用 共享 ， 因 此 对 该 目录 进行 读 写 操作 分 别 需 要 

READ EXTERNAL _STORAGE 和 WRITE_EXTERNAL STORAGE 权 限 。 另 外 ， 因 为 写 权 限 
隐 含 了 读 权 限 ， 所 以 如 果 需 要 外 部 存储 的 写 权 限 ， 那 么 仅仅 需要 请 求 一 项 权限 就 可 以 了 : 


<manifest scs 
«uses-permission android:name-"android.permission.WRITE EXTERNAL STORAGE" /» 


«/manifest» 


然而 ， 如 果 希 望 照片 对 我 们 的 应 用 而 言 是 私有 的 ， 那 么 可 以 使 用 getExternalFilesDir() 提 供 的 
目录 。 在 Android 4.3 及 以 下 版 本 的 系统 中 ， 写 这 个 目录 需要 WRITE EXTERNAL STORAGE 
权限 。 从 Android 4.4 开 始 ， 该 目录 将 无 法 被 其 他 应 用 访问 ， 所 以 该 权限 就 不 再 需要 了 ， 你 可 
以 通过 添加 maxSdkVersion 属 性 ， 声 明 只 在 低 版 本 的 Android 设 备 上 请 求 这 个 权限 。 


«manitest ...> 
«uses-permission android:name-"android.permission.WRITE EXTERNAL STORAGE" 
android:maxSdkVersion="18" /> 


«/manifest» 


Note: P A 4 fik% getExternalFilesDir()i2#4 & B 3k F 83 LAE P Sp SU Mapp S tk Ml 


除 。 
一 旦 选 定 了 存储 文件 的 目录 ， 我 们 还 需要 设计 一 个 保证 文件 名 不 会 冲突 的 命名 规则 。 当 然 我 


们 还 可 以 将 路 径 存 储 在 一 个 成 员 变 量 里 以 备 在 将 来 使 有 用。 下面 的 例子 使 用 日 期 时 间 稚 作为 新 
照片 的 文件 名 : 


String mCurrentPhotoPath; 


private File createImageFile() throws IOException { 
// Create an image file name 
String timeStamp = new SimpleDateFormat("yyyyMMdd HHmmss").format(new Date()); 
String imageFileName = "JPEG_" + timeStamp + " "; 
File storageDir - Environment.getExternalStoragePublicDirectory( 
Environment.DIRECTORY PICTURES); 
File image - File.createTempFile( 
imageFileName,  /* prefix */ 
"sere XSufftax 
storageDir Zreceory ia 


); 


// Save a file: path for use with ACTION_VIEW intents 
mCurrentPhotoPath = "file:" + image.getAbsolutePath(); 
return image; 


有 了 上 面 的 方法 ， 我 们 就 可 以 给 新 照片 创建 文件 对 象 了 ， 现 在 我 们 可 以 像 这 样 创建 并 触发 一 
个 Intent : 


static final int REQUEST TAKE PHOTO = 1; 


private void dispatchTakePictureIntent() { 
Intent takePictureIntent - new Intent(MediaStore.ACTION IMAGE CAPTURE); 
// Ensure that there's a camera activity to handle the intent 
if (takePictureIntent.resolveActivity(getPackageManager()) != null) ( 
// Create the File where the photo should go 
File photoFile - null; 
try { 
photoFile = createImageFile(); 
catch (IOException ex) { 
// Error occurred while creating the File 


j 


// Continue only if the File was successfully created 
if (photoFile != null) { 
takePictureIntent.putExtra(MediaStore.EXTRA OUTPUT, 
Uri.fromFile(photoFile)); 
startActivityForResult(takePictureIntent, REQUEST TAKE PHOTO); 


由 于 我 们 通过 |Intent 创 建 了 一 张 照片 ， 因 此 图 片 的 存储 位 置 我 们 是 知道 的 。 对 其 他 人 来 说 ， 也 
许 查看 我 们 的 照片 最 简单 的 方式 是 通过 系统 的 Media Provider ° 


Note: 如 果 将 图 片 存储 在 getExternalFilesDir() 提 供 的 目录 中 ，Media Scanner 将 无 法 访问 
到 我 们 的 文件 ， 因 为 它们 隶属 于 应 用 的 私有 数据 。 


下 面 的 例子 演示 了 如 何 触 发 系统 的 Media Scanner， 将 我 们 的 照片 添加 到 Media Provider 的 数 
据 库 中 ， 这 样 就 可 以 使 得 Android 相 册 程序 与 其 他 程序 能 够 读 取 到 这 些 照片 。 


private void galleryAddPic() { 
Intent mediaScanIntent - new Intent(Intent.ACTION MEDIA SCANNER SCAN FILE); 
File f - new File(mCurrentPhotoPath); 
Uri contentUri - Uri.fromFile(f); 
mediaScanIntent.setData(contentUri); 
this.sendBroadcast(mediaScanIntent); 


解码 一 幅 缩 放 图 片 


在 有 限 的 内 存 下 ， tin 尺寸 的 图 片 会 很 闲 手 。 如 果 发 现 应 用 在 展示 了 少量 图 片 后 消耗 
了 所 有 内 存 ， 我 们 可 以 通过 缩放 图 片 到 目标 视图 尺寸 ， 之 后 再 载 入 到 内 存 中 的 方法 ， 来 显著 
降低 内 存 的 使 用 ， Beds 子 演 示 了 这 个 技术 : 


private void setPic() { 
// Get the dimensions of the View 
int targetW = mImageView.getWidth(); 
int targetH = mImageView.getHeight(); 


// Get the dimensions of the bitmap 

BitmapFactory.Options bmOptions = new BitmapFactory.Options(); 
bmOptions.inJustDecodeBounds = true; 
BitmapFactory.decodeFile(mCurrentPhotoPath, bmoptions); 

int photow - bmOptions.outWidth; 

int photoH = bmOptions.outHeight; 


// Determine how much to scale down the image 
int scaleFactor - Math.min(photow/targetW, photoH/targetH); 


// Decode the image file into a Bitmap sized to fill the View 
bmOptions.inJustDecodeBounds - false; 

bmOptions.inSampleSize = scaleFactor; 

bmOptions.inPurgeable - true; 


Bitmap bitmap - BitmapFactory.decodeFile(mCurrentPhotoPath, bmOptions); 
mImageView.setlImageBitmap (bitmap); 


简单 的 拍照 
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轻松 录制 视频 


编写 :kesenhoo - 原文 :http://developer.android.com/training/camera/videobasics.html 
这 节 课 会 介绍 如 何 使 用 已 有 的 相机 应 用 来 录制 视频 。 


假设 在 我 们 应 用 的 所 有 功能 当中 ， 整 合 视频 只 是 其 中 的 一 小 部 分 ， 我 们 想 要 以 最 简单 的 方法 
录制 视频 ， 而 不 是 重新 实现 一 个 摄像 机 组 件 。 幸 运 的 是 ， 大 多 数 Android 设 备 已 经 安装 了 一 个 
能 录制 视频 的 相机 应 用 。 在 本 节 课 当中 ， 我 们 将 会 让 它 为 我 们 完成 这 一 任务 。 


请 求 相 机 权限 
为 了 让 用 户 知道 我 们 的 应 用 依赖 照相 机 ， 在 Manifest 清 单 文件 中 添加 <uses-feature> 标签 : 


«manifest ... » 
«uses-feature android:name="android.hardware.camera" 
android:required-"true" /» 


«/manifest» 


如 果 应 用 使 用 相机 ， 但 相机 并 不 是 应 用 正常 运行 所 必 不 可 少 的 组 件 ， 可 以 

将 android:required 设置 为 "false" 。 这 样 的 话 ， Google Play 也 会 允许 没有 相机 的 设备 下 载 
该 应 用 。 当 然 我 们 有 必要 在 使 用 相机 之 前 通过 调 

用 hasSystemFeature(PackageManager.FEATURE_CAMERA) 方 法 来 检查 设备 上 是 否 有 相 
机 。 如 果 没 有 ， 那 么 和 相机 相关 的 功能 应 该 禁用 | 


使 用 相机 程序 来 录制 视频 


利用 一 个 描述 了 执行 目的 的 Intent 对 象 ，Android 可 以 将 某 些 执行 任务 委托 给 其 他 应 用 。 整 个 
过 程 包含 三 部 分 : Intent 本 身 ， 一 个 函数 调用 来 启动 外 部 的 Activity， 当 焦点 返回 到 Activity 
时 ， 处 理 返回 图 像 数据 的 代码 。 


下 面 的 函数 将 会 发 送 一 个 Intent 来 录制 视频 


static final int REQUEST VIDEO CAPTURE = 1; 


private void dispatchTakeVideoIntent() { 
Intent takeVideoIntent - new Intent(MediaStore.ACTION VIDEO CAPTURE); 
if (takeVideoIntent.resolveActivity(getPackageManager()) != null) ( 
startActivityForResult(takeVideoIntent, REQUEST VIDEO CAPTURE); 


注意 在 调用 startActivityForResult() 方 法 之 前 ， 先 调用 resolveActivity()， 这 个 方法 会 返回 能 处 


理 该 Intent 的 第 一 个 Activity (译注 : 即 检查 有 没有 能 处 理 这 个 Intent 的 Activity) 。 执 行 这 个 检 
t 


查 非 常 重要 ， 因 为 如 果 在 调用 startActivityForResult() 时 ， 没 有 应 用 能 处 理 你 的 Intent， 应 用 


会 前 溃 。 所 以 只 要 返回 结果 不 为 null， 使 用 该 Intent 就 是 安全 的 。 


查看 视频 


Android 的 相机 程序 会 把 指向 视频 存储 地 址 的 Uri 添 加 到 Intent 中 ， 并 传送 给 onActivityResult() 
方法 。 下 面 的 代码 获取 该 视频 并 显示 到 一 个 VideoView 当 中 : 


@Override 
protected void onActivityResult(int requestCode, int resultCode, Intent data) { 
if (requestCode == REQUEST VIDEO CAPTURE && resultCode == RESULT OK) ( 
Uri videoUri = intent.getData(); 
mVideoView.setVideoURI(videoUri); 


控制 相机 


编写 :kesenhoo@2016/11/30 - 
http://developer.android.com/training/camera/cameradirect.html 


在 这 一 节 课 ， 我 们 会 讨论 如 何 通 过 使 用 Android 框 架 所 提供 的 API 来 直接 控制 相机 硬件 ， 实 现 
自 定 义 相 机 模块 。 


直接 控制 相机 ， 相 比 起 请 求 已 经 存在 的 相机 应 用 进行 拍照 或 录制 视频 ， 要 复杂 一 些 。 这 节 课 
将 会 讲解 如 何 创建 一 个 专业 的 相机 应 用 并 将 其 整合 到 我 们 自己 的 应 用 界面 中 去 。 


打开 相机 对 象 


获取 一 个 Camera 实例 是 直接 控制 相机 的 第 一 步 。 正 如 Android 自 带 的 Camera 程 序 一 样 ， 推 
荐 的 方式 是 在 Activity 的 onCreate() 方 法 里 面 另 起 一 个 线程 ， 在 这 个 单独 的 线程 里 面 对 Camera 
进行 操作 。 在 单独 的 线程 里 面 访问 Camera 实 例 可 以 避免 操作 Camera 实 例 的 时 间 较 长 而 导致 
UI 线程 被 阻塞 。 更 基础 的 实现 方式 是 ， 编 写 一 个 打开 Camera 的 方法 ， 这 个 方法 可 以 

在 onResume() 方 法 里 面 去 调用 执行 ， 单 独 的 方法 使 得 代码 更 容易 重用 ， 也 便于 保持 控制 流程 
更 加 简单 。 


如 果 我 们 在 执行 Camera.open() 方 法 的 时 候 Camera 正 在 被 另外 一 个 应 用 使 用 ， 那 么 函数 会 抛 
出 一 个 Exception， 我 们 可 以 利用 try 语句 块 进行 捕获 : 


private boolean safeCameraOpen(int id) { 
boolean qOpened - false; 


try { 
releaseCameraAndPreview(); 


mCamera - Camera.open(id); 
qOpened - (mCamera !- null); 
} catch (Exception e) { 
Log.e(getString(R.string.app name), "failed to open Camera"); 
e.printStackTrace(); 


} 


return qOpened; 


} 


private void releaseCameraAndPreview() { 
mPreview.setCamera(null); 
if (mCamera != null) { 
mCamera.release(); 
mCamera = null; 


Á MAPI level 9 开始 ， 相 机 框架 可 以 支持 多 个 摄像 头 的 打开 操作 。 如 果 使 用 昌 的 APl， 在 调 
用 open() 时 不 传 入 参数 指定 打开 哪个 摄像 头 ， 默 认 情 况 下 会 使 用 后 置 摄像 头 。 


创建 相机 预览 界面 


拍照 通常 需要 向 用 户 提供 一 个 预览 界面 来 显示 待 拍 摄 的 画面 内 容 。 我 们 可 以 使 用 SurfaceView 
Rn 


Preview 预 览 组 件 


我 们 需要 使 用 preview class 来 显示 预览 界面 。 这 个 类 需要 实 
现 android.view.SurfaceHolder.Callback 接口 ， 它 会 用 这 个 接口 把 相机 硬件 获取 到 的 图 像 数据 


传递 给 应 用 程序 e 


class Preview extends ViewGroup implements SurfaceHolder.Callback { 


SurfaceView mSurfaceView; 
SurfaceHolder mHolder; 


Preview(Context context) { 
super(context); 


mSurfaceView - new SurfaceView(context); 
addView(mSurfaceView); 


// Install a SurfaceHolder.Callback so we get notified when the 
// underlying surface is created and destroyed. 

mHolder - mSurfaceView.getHolder(); 

mHolder.addCallback(this); 
mHolder.setType(SurfaceHolder.SURFACE TYPE PUSH BUFFERS); 


为 了 能 够 呈现 相机 图 像 画 面 ，Preview 类 必须 先 获取 Camera 实 例 。 


设置 和 启动 Preview 


一 个 Camera 实 例 与 它 相 关 的 Preview 必 须 按照 特定 的 顺序 来 创建 ， 通 常 来 说 Camera 对 象 优 先 
被 创建 。 在 下 面 的 示例 中 ， 初 始 化 Camera 的 动作 被 封装 了 起 来 ， 这 样 ， 无 论 用 户 想 对 
Camera 做 什么 样 的 改变 ，Camera.startPreview() 都 会 被 setcamera() 调用 。 另 外 ，Preview 
xt Rsb FE surfacechanged() 这 一 回调 方法 里 面 重新 启用 (restart) 。 


public void setCamera(Camera camera) { 
if (mCamera == camera) { return; } 


stopPreviewAndFreeCamera(); 
mCamera = camera; 


if (mCamera != null) { 
List<Size> localSizes = mCamera.getParameters().getSupportedPreviewSizes(); 
mSupportedPreviewSizes = localSizes; 
requestLayout(); 


try { 
mCamera.setPreviewDisplay(mHolder); 


catch (IOException e) { 
e.printStackTrace(); 


// Important: Call startPreview() to start updating the preview 
// surface. Preview must be started before you can take a picture. 
mCamera.startPreview(); 


修改 相机 设置 


相机 参数 的 修改 可 以 改变 拍照 的 成 像 效 果 ， 例 如 缩放 大 小 ， 曝 光 补 偿 值 等 等 。 下 面 的 例子 仅 
仅 演示 了 如 何 改变 预览 大 小 ， 更 多 设置 请 参考 相机 应 用 的 源 代码 。 


public void surfaceChanged(SurfaceHolder holder, int format, int w, int h) { 
// Now that the size is known, set up the camera parameters and begin 
// the preview. 
Camera.Parameters parameters - mCamera.getParameters(); 
parameters.setPreviewSize(mPreviewSize.width, mPreviewSize.height); 
requestLayout(); 
mCamera.setParameters(parameters); 


// Important: Call startPreview() to start updating the preview surface. 
// Preview must be started before you can take a picture. 
mCamera.startPreview(); 


大 多 数 相 机 程序 会 锁定 预览 方向 为 横 屏 状态 ， 因 为 该 方向 是 相机 传感器 的 自然 放置 方向 。 当 
然 这 一 设 定 并 不 妨碍 我 们 去 拍 坚 屏 的 照片 ， 这 个 时 候 设 备 的 方向 角度 信息 会 被 记录 在 EXIF 文 
件 头 中 。setCameraDisplayOrientation() 方 法 可 以 让 你 在 不 影响 照片 拍摄 过 程 的 情况 下 ， 改 变 
预览 的 方向 。 然 而 ， 对 于 Android API level 14 及 更 日 版 本 的 系统 ， 在 改变 方向 之 前 ， 我 们 必 
须 先 停止 相机 预览 ， 设置 方向 之 后 ， 然 后 再 重启 预览 。 


拍 摄 照 AS 


一 旦 预览 启动 成 功 之 后 ， 可 以 使 用 Camera.takePicture() 方 法 拍摄 照片 。 我 们 可 以 创建 
Camera.PictureCallback 与 Camera.ShutterCallback 对 象 并 将 他 们 传递 
到 Camera.takePicture() 中 。 


如 果 我 们 想 要 获取 每 一 帧 的 相机 画面 ， 可 以 创建 一 个 Camera.PreviewCallback 并 实现 
onPreviewFrame() 回 调 。 我 们 可 以 取景 画面 帧 进行 保存 ， 也 可 以 延迟 调用 takePicture() 来 进行 
拍照 。 


* B Preview 


在 拍摄 好 图 片 后 ， 我 们 必须 在 用 户 拍 下 一 张 图 片 之 前 重启 预览 。 下 面 的 示例 是 根据 快门 按钮 
的 不 同 状态 来 实现 重启 预览 。 


@Override 
public void onClick(View v) { 
switch(mPreviewState) { 
case K_STATE_FROZEN: 
mCamera.startPreview(); 
mPreviewState - K STATE PREVIEW; 
break; 


default: 
mCamera.takePicture( null, rawCallback, null); 
mPreviewState - K STATE BUSY; 

) // switch 

shutterBtnConfig(); 


停止 预览 并 释放 相机 


当 应 用 使 用 完 相 机 之 后 ， 我 们 有 必要 进行 清理 释放 资源 的 操作 。 尤 其 是 ， 我 们 必须 释 
放 Camera 对 象 ， 不 然 的 话 可 能 会 引起 其 他 应 用 程序 使 用 Camera 实 例 的 时 候 发 生 崩 演 ， 和 包括 
我 们 自己 应 用 也 同样 会 遇 到 这 个 问题 。 





那么 何 时 应 该 停止 预览 并 释放 相机 呢 ? 在 预览 Surface 组 件 被 销毁 之 后 ， 可 以 做 停止 预览 与 释 


放 相 机 的 操作 。 如 下 面 Preview 类 中 的 方法 所 做 的 那样 : 


public void surfaceDestroyed(SurfaceHolder holder) { 
// Surface will be destroyed when we return, so stop the preview. 
if (mCamera != null) { 
// Call stopPreview() to stop updating the preview surface. 
mCamera.stopPreview(); 


SUE 
* when this function returns, mCamera will be null. 
ph 

private void stopPreviewAndFreeCamera() { 


if (mCamera !- null) { 
// Call stopPreview() to stop updating the preview surface. 
mCamera.stopPreview(); 


// Important: Call release() to release the camera for use by other 
// applications. Applications should release the camera immediately 


// during onPause() and re-open() it during onResume()) 
mCamera.release(); 


mCamera = null; 


在 这 节 课 的 前 部 分 中 ， 这 一 些 系 列 的 动作 也 是 setcamera() 方法 的 一 部 分 ， 因 此 初始 化 一 个 相 


机 的 动作 ， 总 是 从 停止 预览 开始 的 。 
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打印 


编写 :jdneo - 原文 :http://developer.android.com/training/printing/index.html 


Android 用 户 经 常 需要 在 设备 上 单独 地 阅览 信息 ， 但 有 时 候 也 需要 为 了 分 享 信息 而 不 得 不 给 其 
他 人 看 自己 设备 的 屏幕 ， 这 显然 不 是 分 享 信息 的 好 办 法 。 如 果 我 们 可 以 通过 Android 应 用 把 希 
望 分 享 的 信息 打印 出 来 ， 这 将 给 用 户 提 供 一 种 从 应 用 获取 更 多 信息 的 好 办 法 ， 更 何况 这 么 做 
还 能 将 信息 分 享 给 其 他 那些 不 使 用 我 们 的 应 用 的 人 。 另 外 ， 打 印 服务 还 能 创建 信息 的 快照 
(生成 PDF 文件 ) ， 而 这 一 切 不 需要 打印 设备 ， 无 线 网 络 连 接 ， 也 不 会 消耗 过 多 电量 。 
在 Android 4.4 (API Level 19) 及 更 高 版 本 的 系统 中 ， 框 架 提供 了 直接 从 Android 应 用 程序 打 
印 图 片 和 文字 的 服务 。 这 系列 课程 将 展示 如 何 启 用 打印 : 包括 打印 图 片 ，HTML 页 面 以 及 创建 
自 定 义 的 打印 文档 。 


Lessons 


e 打印 照片 
这 节 课 将 展示 如 何 打 印 一 幅 图 像 。 
e 打印 HTML 文 档 
这 节 课 将 展示 如 何 打印 一 个 HTML 文 档 。 
e 打印 自 定义 文档 
x 节 课 将 展示 如 何 连 接 到 Android 打 印 管 理 器 ， 创 建 一 个 打印 适配器 并 建立 要 打印 的 内 


这 


o 


打印 照片 


编写 :jdneo - 原文 :http://developer.android.com/training/printing/photos.html 
J p p g/p g/p 


拍摄 并 分 享 照片 是 移动 设备 最 流行 的 用 法 之 一 。 如 果 我 们 的 应 用 拍摄 了 照片 ， 并 期 望 可 以 展 
示人 他们， 或 者 允许 用 户 共享 上 照片， 那么 SUM ee ASI qua 文 些 照片 

来 。Android Support Library 提 供 了 一 个 方便 的 函数 ， 通 过 这 一 函数 ， 仅 仅 使 用 很 少量 的 代码 
和 一 些 简单 的 打印 布局 配置 集 ， 就 能 够 进行 照片 打印 。 


这 堂 课 将 展示 如 何 使 用 v4 support library 中 的 PrintHelper 类 打印 一 幅 图 片 。 


打印 一 幅 图 片 


Android Support Library 中 的 PrintHelper 类 提供 了 一 种 打印 图 片 的 简单 方法 。 该 类 有 一 个 单一 
的 布局 选项 : setScaleMode()， 它 允许 我 们 使 用 下 面 的 两 个 选项 之 一 : 


e SCALE MODE FIT : 该 选项 会 调整 图 像 的 大 小 ， 这 样 整 个 图 像 就 会 在 打印 有 效 区 域内 全 
部 显示 出 来 (等 比例 缩放 至 长 和 宽 都 包含 在 纸张 页 面 内 ) 。 

e SCALE MODE FILL : 该 选项 同样 会 等 比例 地 调整 图 像 的 大 小 使 图 像 充满 整个 打印 有 效 
区 域 ， 即 让 图 像 充 满 整 个 纸张 页 面 。 这 就 意味 着 如 果 选 择 这 个 选项 ， 那 么 图 片 的 一 部 分 
(顶部 和 底部 ， 或 者 左 侧 和 右 侧 ) 将 无 法 打印 出 来 。 如 果 不 设置 图 像 的 打印 布局 选项 ， 
该 模式 将 是 默认 的 图 像 拉 伸 方式 。 


这 两 个 setScaleMode() 的 图 像 布 局 选项 都 会 保持 图 像 原 有 的 长 帘 比 。 下 面 的 代码 展示 了 如 何 
创建 一 个 PrintHelper 类 的 实例 ， 设 置 布局 选项 ， 并 开始 打印 进程 : 


private void doPhotoPrint() { 
PrintHelper photoPrinter - new PrintHelper(getActivity()); 
photoPrinter.setScaleMode(PrintHelper.SCALE MODE FIT); 
Bitmap bitmap - BitmapFactory.decodeResource(getResources(), 
R.drawable.droids); 
photoPrinter.printBitmap("droids.jpg - test print", bitmap); 


该 方法 可 以 作为 一 个 菜单 项 的 Action 来 被 调用 。 注 意 对 于 那些 不 一 定 被 设备 支持 的 菜单 项 ( 比 
如 有 些 设备 可 能 无 法 支持 打印 ) ， 应 该 放置 在 “更 多 菜单 (overflow menu) "中 。 要 获取 有 关 
这 方面 的 更 多 知识 ， 可 以 阅读 : Action Bar。 


在 printBitmap() 被 调用 之 后 ， 我 们 的 应 用 就 不 再 需要 进行 其 他 的 操作 了 。 之 后 Android 打 印 界 
面 就 会 出 现 ， 允 许 用 户 选择 一 个 打印 机 和 它 的 打印 选项 。 用 户 可 以 打印 图 像 或 者 取消 这 一 次 
操作 。 如 果 用 户 选择 了 打印 图 像 ， 那 么 一 个 打印 任务 将 会 被 创建 ， 同 时 在 系统 的 通知 栏 中 会 


显示 一 个 打印 提醒 通知 。 


如 果 项 望 在 打印 输出 中 包含 更 多 的 内 容 ， 而 不 仅仅 是 一 张 图 片 ， 那 么 就 必须 构造 一 个 打印 文 
档 。 这 方面 知识 将 会 在 后 面 的 两 节 课程 中 展开 。 
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如 果 要 在 Android 上 打印 比 一 副 有 照片 更 丰富 的 内 容 ， 我 们 需要 将 文本 和 图 片 组 合 在 一 个 待 打印 
的 文档 中 。Android 框 架 提供 了 一 种 使 用 HTML 语 言 来 构建 文档 并 进行 打印 的 方法 ， 它 使 用 的 
代码 数量 是 很 小 的 。 


WebView 类 在 Android 4.4 (API Level 19) 中 得 到 了 更 新 ， 使 得 它 可 以 打印 HTML 内 容 。 该 类 
允许 我 们 加 载 一 个 本 地 HTML 资 源 或 者 从 网 页 下 载 一 个 页 面 ， 创 建 一 个 打印 任务 ， 并 把 它 交 给 
Android 打 印 服务 。 


这 节 课 将 展示 如 何 快速 地 构建 一 个 包含 有 文本 和 图 片 的 HTML 文 档 ， 以 及 如 何 使 用 WebView 打 
印 该 文档 。 


加 载 一 个 HTML 文 档 


用 WebView 打 印 一 个 HTML 文 档 ， 会 涉及 到 加 载 一 个 HTML 资 源 ， 或 者 用 一 个 字符 串 构建 
HTML 文 档 。 这 一 节 将 描述 如 何 构 建 一 个 HTML 的 字符 串 并 将 它 加 载 到 WebView 中 ， 以 备 打 
印 o 

该 View 对 象 一 般 被 用 来 作为 一 个 Activity 布 局 的 一 部 分 。 然 而 ， 如 果 应 用 当前 并 没有 使 

用 WebView， 我 们 可 以 创建 一 个 该 类 的 实例 ， 以 进行 打印 。 创 建 该 自 定 义 View 的 主要 步骤 


a 


Fees 


1， 在 HTML 资 源 加 载 完 毕 后 ， 创 建 一 个 WebViewClient 用 来 启动 一 个 打印 任务 。 
2， 加 载 HTML 资 源 至 WebView 对 象 中 。 


下 面 的 代码 展示 了 如 何 创建 一 个 简单 的 WebViewClient 并 且 加 载 一 个 动态 创建 的 HTML 文 档 : 


打印 HTML 文 档 


private WebView mWebView; 


private void doWebViewPrint() { 
// Create a WebView object specifically for printing 
WebView webView = new WebView(getActivity()); 
webView.setWebViewClient(new WebViewClient() { 


public boolean shouldOverrideUrlLoading(WebView view, String url) { 
return false; 


@Override 

public void onPageFinished(WebView view, String url) { 
Log.i(TAG, "page finished loading " + url); 
createWebPrintJob(view) ; 
mWebView = null; 


3); 


// Generate an HTML document on the fly: 

String htmlDocument = "<html><body><hi>Test Content«/hi»«p»Testing, " + 
"testing, testing...</p></body></html>"; 

webView.loadDatawithBaseURL(null, htmlDocument, "text/HTML", "UTF-8", null); 


// Keep a reference to WebView object until you pass the PrintDocumentAdapter 
// to the PrintManager 
mWebView = webView; 


Note : 请 确保 在 WebViewClient) 中 的 onPageFinished() 方 法 内 调用 创建 打印 任务 的 方 
法 。 如 果 没 有 等 到 页 面 加 载 完毕 就 进行 打印 ， 打 印 的 输出 可 能 会 不 完整 或 空白 ， 甚 至 可 
能 SEED 


Note : 在 上 面 的 样 例 代 码 中 ， 保 留 了 一 个 WebView 对 得 实例 的 引用 ， 这 样 能 够 确保 它 不 
会 在 打印 任务 创建 之 前 就 被 垃圾 回收 器 所 回收 。 在 编写 代码 时 请 务必 这 样 做 ， 否 则 打印 
的 进程 可 能 会 无 法 继续 执行 。 


如 果 我 们 希望 页 面 中 包含 图 像 ， 将 这 个 图 像 文件 放置 在 你 的 工程 的 “assets/" 目 录 中 ， 并 指定 一 
个 基 URL (Base URL) ， 并 将 它 作为 loadDataWithBaseURL() 方 法 的 第 一 个 参数 ， 就 像 下 面 
所 显示 的 一 样 : 


webView.loadDataWithBaseURL("file:///android asset/images/", htmlBody, 
"text/HTML", "UTF-8", null); 


我 们 也 可 以 加 载 一 个 需要 打印 的 网 页 ， 具 体 做 法 是 将 loadDataWithBaseURL() 方 法 替换 
为 loadUrl()， 如 下 所 示 : 
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// Print an existing web page (remember to request INTERNET permission!): 
webView.loadUrl("http://developer.android.com/about/index.html"); 


当 使 用 WebView 创 建 打印 文档 时 ， 你 要 注意 下 面 的 一 些 限 制 : 


© 不 能 为 文档 添加 页 下 和 页 脚 ， 包 括 页 号 。 

e HTML 文 档 的 打印 选项 不 包含 选择 打印 的 页 数 范围 ， 例 如 : 对 于 一 个 10 页 的 HTMI 文 档 ， 
只 打印 2 到 4 页 是 不 可 以 的 。 

e 一 个 WebView 的 实例 只 能 在 同一 时 间 处 理 一 个 打印 任务 。 

e. 若 一 个 HTML 文 档 包 含 CSS 打 印 属性 ， 比 如 一 个 landscape 属 性 ， 这 是 不 被 支持 的 。 

e 不 能 通过 一 个 HTML 文 档 中 的 JavaScript 脚 本 来 激活 打印 。 


Note: 一 旦 在 布局 中 包含 的 WebView 对 月 将 文档 加 载 完 毕 后 ， 就 可 以 打印 WebView 对 篆 
的 内 容 了 。 


如 果 和 希望 创建 一 个 更 加 自 定义 化 的 打印 输出 并 希望 可 以 完全 控制 打印 页 面 上 绘制 的 内 容 ， 可 
以 学 习 下 一 节 课 程 : 打印 自 定义 文档 


创建 一 个 打印 任务 


在 创建 了 WebView 并 加 载 了 我 们 的 HTML 内 容 之 后 ， 应 用 就 已 经 几乎 完成 了 属于 它 的 任务 。 接 
下 来 ， 我 们 需要 访问 PrintManager， 创 建 一 个 打印 适配器 ， 并 在 最 后 创建 一 个 打印 任务 。 下 
面 的 代码 展示 了 如 何 执行 这 些 步骤 : 


private void createWebPrintJob(WebView webView) { 


// Get a PrintManager instance 
PrintManager printManager - (PrintManager) getActivity() 
.getSystemService(Context.PRINT SERVICE); 


// Get a print adapter instance 
PrintDocumentAdapter printAdapter - webView.createPrintDocumentAdapter(); 


// Create a print job with name and adapter instance 

String jobName = getString(R.string.app name) + " Document"; 

PrintJob printJob - printManager.print(jobName, printAdapter, 
new PrintAttributes.Builder().build()); 


// Save the job object for later status checking 
mPrintJobs.add(printJob); 


这 个 例子 保存 了 一 个 PrintJob 对 象 的 实例 ， 以 供 我 们 的 应 用 将 来 使 用 ， 当 然 这 是 不 必须 的 。 我 
们 的 应 用 可 以 使 用 这 个 对 象 来 跟踪 打印 任务 执行 时 的 进度 。 如 果 和 希望 监 控 应 用 中 的 打印 任务 
是 否 完成 ， 是 否 失败 或 者 是 否 被 用 户 取消 ， 这 个 方法 非常 有 有 用。 另外， 我 们 不 需要 创建 一 个 
应 用 内 置 的 通知 ， 因 为 打印 框架 会 自动 的 创建 一 个 该 打印 任务 的 系统 通知 。 


打印 自 定 义 文 档 
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对 于 有 些 应 用 ， 比 如 绘图 应 用 ， 页 面 布局 应 用 和 其 它 一 些 关 注 于 图 像 输出 的 应 用 ， 创 造 出 精 
美的 打印 页 面 将 是 它 的 核心 功能 。 在 这 种 情况 下 ， 仅 仅 打 印 一 幅 图 片 或 一 个 HTML 文 档 就 不 够 
了 。 这 类 应 用 的 打印 输出 需要 精确 地 控制 每 一 个 会 在 页 面 中 显示 的 对 象 ， 包 括 字 体 ， 文 本 
流 ， 分 页 符 ， 页 眉 ， 页 脚 和 一 些 图 像 元 素 等 等 。 


想 要 创建 一 个 完全 自 定 义 的 打印 文档 ， 需 要 投入 比 之 前 讨论 的 方法 更 多 的 编程 精力 。 我 们 必 
须 构建 可 以 和 打印 框架 相互 通信 的 组 件 ， 调 整 打印 参数 ， 绘 制 页 面 元 素 并 管理 多 个 页 面 的 打 
印 。 


这 节 课 将 展示 如 何 连 接 打印 管理 器 ， 创 建 一 个 打印 适配器 以 及 如 何 构建 出 需要 打印 的 内 容 。 
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当 我 们 的 应 用 直接 管理 打印 进程 时 ， 在 收 到 来 自用 户 的 打印 请 求 后 ， 第 一 步 要 做 的 是 连接 
Android 打 印 框架 并 获取 一 个 PrintManager 类 的 实例 。 该 类 允许 我 们 初始 化 一 个 打印 任务 并 开 
始 打印 任务 的 生命 周期 。 下 面 的 代码 展示 了 如 何 获得 打印 管理 器 并 开始 打印 进程 。 


private void doPrint() { 
// Get a PrintManager instance 
PrintManager printManager - (PrintManager) getActivity() 
.getSystemService(Context.PRINT SERVICE); 


// Set job name, which will be displayed in the print queue 
String jobName = getActivity().getString(R.string.app name) + " Document"; 


// Start a print job, passing in a PrintDocumentAdapter implementation 

// to handle the generation of a print document 

printManager.print(jobName, new MyPrintDocumentAdapter(getActivity()), 
NCS) A 


上 面 的 代码 展示 了 如 何 命名 一 个 打印 任务 以 及 如 何 设置 一 个 PrintDocumentAdapter 类 的 实 
例 ， 它 负责 处 理 打印 生命 周期 的 每 一 步 。 打 印 适配器 的 实现 会 在 下 一 节 中 进行 讨论 。 


Note : print() 方 法 的 最 后 一 个 参数 接收 一 个 PrintAttributes 对 象 。 我 们 可 以 使 用 这 个 参数 
向 打印 框架 进行 一 些 打印 设置 ， 以 及 基于 前 一 个 打印 周期 的 预 设 ， 从 而 改善 用 户 体 验 。 
我 们 也 可 以 使 用 这 个 参数 对 打印 内 容 进行 一 些 更 符合 实际 情况 的 设置 ， 比 如 当 打 印 一 幅 
照片 时 ， 设 置 打 印 的 方向 与 照片 方向 一 致 。 


创建 打印 适配器 


打印 适配器 负责 与 Android 打 印 框 架 交 互 并 处 理 打 印 过 程 的 每 一 步 。 过 程 需要 用 户 在 创建 
打印 文档 前 选择 打印 机 和 打印 选 et et 
或 不 同 的 页 面 方向 ， 因 此 这 些 选 项 可 能 会 影响 最 终 的 打印 效果 。 当 这 些 选项 配置 好 之 后 ， 打 
印 框架 会 寻求 适配器 we 
击 了 打印 按钮 ， 框 架 会 将 最 终 的 打印 文档 传递 给 Print Provider 进 行 打印 输出 。 在 打印 过 

中 ， 用 户 可 以 选择 取消 打印 ， 所 以 打印 适配器 必须 监听 并 响应 取消 打印 的 请 求 。 


PrintDocumentAdapter 抽 象 类 负责 处 理 打印 的 生命 周期 ， 它 有 四 个 主要 的 回调 方法 。 我 们 必 
须 在 打印 适配器 中 实现 这 些 方法 ， 以 此 来 正确 地 和 Android 打 印 框架 进行 交互 : 


e onStart() : 一 旦 打印 进程 开始 ， 该 方法 就 将 被 调用 。 如 果 我 们 的 应 用 有 任何 一 次 性 的 准备 
任务 要 执行 ， 比 如 获取 一 个 要 打印 数据 的 快照 ， 那 么 让 它们 在 此 处 执行 。 在 你 的 适配器 
中 ， 这 个 回调 方法 不 是 必须 实现 的 。 

e onLayout() : 每 当 用 户 改变 了 影响 打印 输出 的 设置 时 (比如 改变 了 页 面 的 尺寸 ， 或 者 页 面 
的 方向 ) 该 函数 将 会 被 调用 ， 以 此 给 我 们 的 应 用 一 个 机 会 去 重新 计算 打印 页 面 的 布局 。 
另外 ， 该 方法 必须 返回 打印 文档 包含 多 少 页 面 。 

e onWrite() : 该 方法 调用 后 ， 会 将 打印 页 面 泻 当成 一 个 待 打 印 的 文件 。 该 方法 可 以 
在 onLayout() 方 法 被 调用 后 调用 一 次 或 多 次 。 

e onFinish() : 一 旦 打印 进程 结束 后 ， 该 方法 将 会 被 调用 。 如 果 我 们 的 应 用 有 任何 一 次 性 销 
毁 任 务 要 执行 ， 让 这 些 任 务 在 该 方法 内 执行 。 这 个 回调 方法 不 是 必须 实现 的 。 


下 面 将 介绍 如 何 实现 onLayout() 以 及 onwrite() 方法 ， 他 们 是 打印 适配器 的 核心 功能 。 


Note : 这 些 适配器 的 回调 方法 会 在 应 用 的 主线 程 上 被 调用 。 如 果 这 些 方法 的 实现 在 执行 
时 可 能 需要 花费 大 量 的 时 间 ， 那 么 应 该 将 他 们 放 在 另 一 个 线程 里 执行 。 例 如 : 我 们 可 以 
将 布局 或 者 写 入 打印 文档 的 操作 封装 在 一 个 AsyncTask 对 象 中 。 


计算 打印 文档 信息 


在 实现 PrintDocumentAdapter 类 时 ， 我 们 的 应 用 必须 能 够 指定 出 所 创建 文档 的 类 型 ， 计 算出 
打印 任务 所 需要 打印 的 总 页 数 ， 并 提供 打印 页 面 的 尺寸 信息 。 在 实现 适配器 的 onLayout() 方 法 
时 ， 我 们 执行 这 些 计算 ， 并 提供 与 理想 的 输出 相关 的 一 些 信息 ， 这 些 信 息 可 以 

在 PrintDocumentlnfo 类 中 获取 ， 包 括 页 数 和 内 容 类 型 。 下 面 的 例子 展示 了 
PrintDocumentAdapter 中 onLayout() 方 法 的 基本 实现 : 


@Override 
public void onLayout(PrintAttributes oldAttributes, 
PrintAttributes newAttributes, 
CancellationSignal cancellationSignal, 
LayoutResultCallback callback, 
Bundle metadata) { 
// Create a new PdfDocument with the requested page attributes 
mPdfDocument = new PrintedPdfDocument(getActivity(), newAttributes); 


// Respond to cancellation request 

if (cancellationSignal.isCancelled() ) { 
callback.onLayoutCancelled(); 
return; 


// Compute the expected number of printed pages 
int pages = computePageCount(newAttributes); 


if (pages > 0) { 
// Return print information to print framework 
PrintDocumentInfo info = new PrintDocumentInfo 
.Builder("print output.pdf") 
.setContentType(PrintDocumentInfo.CONTENT TYPE DOCUMENT) 
.setPageCount(pages); 
.build(); 
// Content layout reflow is complete 
callback.onLayoutFinished(info, true); 
) else { 
// Otherwise report an error to the print framework 
callback.onLayoutFailed("Page count calculation failed."); 


onLayout() 方 法 的 执行 结果 有 三 种 : 完成 ， 取 消 或 失败 (计算 布局 无 法 顺利 完成 时 会 失败 ) 。 
我 们 必须 通过 调用 PrintDocumentAdapter.LayoutResultCallback 对 象 中 的 适当 方法 来 指出 这 
些 结果 中 的 一 个 。 


Note : onLayoutFinished() 方 法 的 布尔 类 型 参数 明确 了 这 个 布局 内 容 是 否 和 上 一 次 打印 请 
求 相 比 发 生 了 改变 。 恰 当地 设 定 了 这 个 参数 将 避免 打印 框架 不 必要 地 调用 onWrite() 方 
法 ， 缓 存 之 前 的 打印 文档 ， 提 升 执行 性 能 。 


onLayout() 的 主要 任务 是 计算 打印 文档 的 页 数 ， 并 将 它 作为 打印 参数 交 给 打印 机 。 如 何 计算 页 
数 则 高 度 依赖 于 应 用 是 如 何 对 打印 页 面 进行 布局 的 。 下 面 的 代码 展示 了 页 数 是 如 何 根据 打印 
方向 确定 的 : 


N 
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private int computePageCount(PrintAttributes printAttributes) { 
int itemsPerPage - 4; // default item count for portrait mode 


MediaSize pageSize = printAttributes.getMediaSize(); 
if (!pageSize.isPortrait()) 1 
// Six items per page in landscape orientation 
itemsPerPage - 6; 


} 


// Determine number of print items 
int printItemCount = getPrintItemCount(); 


return (int) Math.ceil(printItemCount / itemsPerPage); 


将 打印 文档 写 入 文件 


当 需 要 将 打印 内 容 输出 到 一 个 文件 时 ，Android 打 印 框架 会 调用 PrintDocumentAdapter 类 的 
onWrite() 方 法 。 这 个 方法 的 参数 指定 了 哪些 页 面 要 被 写 入 以 及 要 使 用 的 输出 文件 。 该 方法 的 
实现 必须 将 每 一 个 请 求 页 的 内 容 渔 染 成 一 个 含有 多 个 页 面 的 PDF 文件 。 当 这 个 过 程 结束 以 
后 ， 你 需要 调用 callback 对 象 的 onWriteFinished() 方 法 。 
Note : Android 打 印 框架 可 能 会 在 每 次 调用 onLayout() 后 ， 调 用 onWrite() 方 法 一 次 甚至 更 
多 次 。 请 务必 牢记 : 当 打 印 内 容 的 布局 没有 变化 时 ， 可 以 将 onLayoutFinished() 方 法 的 布 
尔 参 数 设置 为 “false”， 以 此 避免 对 打印 文档 进行 不 必要 的 重 写 操作 。 


Note : onLayoutFinished() 方 法 的 布尔 类 型 参数 明确 了 这 个 布局 内 容 是 否 和 上 一 次 打印 请 
求 相 比 发 生 了 改变 。 恰 当地 设 定 了 这 个 参数 将 避免 打印 框架 不 必要 的 调用 onLayout() 方 
法 ， 绥 存 之 前 的 打印 文档 ， 提 升 执行 性 能 。 


下 面 的 代码 展示 了 使 用 PrintedPdfDocument 类 创建 了 PDF 文件 的 基本 原理 : 
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@Override 
public void onWrite(final PageRange[] pageRanges, 
final ParcelFileDescriptor destination, 
final CancellationSignal cancellationSignal, 
final WriteResultCallback callback) { 
// Iterate over each page of the document, 
// check if it's in the output range. 
for (int i = 0; i < totalPages; i++) { 
// Check to see if this page is in the output range. 
if (containsPage(pageRanges, i)) { 
// If so, add it to writtenPagesArray. writtenPagesArray.size() 
// is used to compute the next output page index. 
writtenPagesArray.append(writtenPagesArray.size(), i); 
PdfDocument.Page page - mPdfDocument.startPage(i); 


// check for cancellation 

if (cancellationSignal.isCancelled()) { 
callback.onWriteCancelled(); 
mPdfDocument.close(); 
mPdfDocument - null; 
return, 


// Draw page content for printing 
drawPage (page); 


// Rendering is complete, so page can be finalized. 
mPdfDocument.finishPage(page); 


// Write PDF document to file 
try { 
mPdfDocument.writeTo(new FileOutputStream( 
destination.getFileDescriptor())); 
) catch (IOException e) { 
callback.onwriteFailed(e.toString()); 
fe tsm 
} finally { 
mPdfDocument.close(); 
mPdfDocument - null; 
} 
PageRange[] writtenPages = computeWrittenPages(); 
// Signal the print framework the document is complete 
callback.onWriteFinished(writtenPages) ; 


代码 中 将 PDF 页 面 递交 给 了 drawPage() 方 法 ， 这 个 方法 会 在 下 一 部 分 介绍 。 


就 布局 而 言 ， onWrite() 方 法 的 执行 可 以 有 三 种 结果 : 完成 ， 取 消 或 者 失败 (内容 无 法 被 写 
A) 。 我 们 必须 通过 调用 PrintDocumentAdapter. WriteResultCallback 对 象 中 的 适当 方法 来 指 
明 这 些 结果 中 的 一 个 。 


Note : 泻 业 打印 文档 是 一 个 可 能 耗费 大 量 资源 的 操作 。 为 了 避免 阻塞 应 用 的 主 U 线 程 ， 
我 们 应 该 考虑 将 页 面 的 演 染 和 写 操 作 放 在 另 一 个 线程 中 执行 ， 比 如 在 AsyncTask 中 执行 。 
关于 更 多 异步 任务 线程 的 知识 ， 可 以 阅读 : Processes and Threads。 


绘制 PDF 页 面 内 容 


当 我 们 的 应 用 进行 打印 时 ， 应 用 必须 生成 一 个 PDF 文 档 并 将 它 传递 给 Android 打 印 框架 以 进行 
打印 。 我 们 可 以 使 用 任何 PDF 生成 库 来 协助 完成 这 个 操作 。 本 节 将 展示 如 何 使 
用 PrintedPdfDocument 类 将 打印 内 容 生 成 为 PDF 页 面 。 


PrintedPdfDocument 类 使 用 一 个 Canvas 对 象 来 在 PDF 页 面 上 绘制 元 素 ， 这 一 点 和 在 activity 布 
局 上 进行 绘制 很 类 似 。 我 们 可 以 在 打印 页 面 上 使 用 Canvas 类 提供 的 相关 绘图 方法 绘制 页 面 元 
素 。 下 面 的 代码 展示 了 如 何 使 用 这 些 方法 在 PDF 页 面 上 绘制 一 些 简单 的 元 素 : 


private void drawPage(PdfDocument.Page page) { 
Canvas canvas - page.getCanvas(); 


// units are in points (1/72 of an inch) 
int titleBaseLine = 72; 
int leftMargin = 54; 


Paint paint = new Paint(); 

paint .setColor(Color.BLACk) ; 

paint.setTextSize(36); 

canvas.drawText("Test Title", leftMargin, titleBaseLine, paint); 


paint.setTextSize(11); 
canvas.drawText("Test paragraph", leftMargin, titleBaseLine + 25, paint); 


paint.setColor(Color.BLUE); 
canvas.drawRect(100, 100, 172, 172, paint); 


当 使 用 Canvas 在 一 个 PDF 页 面 上 绘图 时 ， 元 素 通 过 单位 “点 (point) "来 指定 大 小 ， 一 个 点 相 
当 于 七 十 二 分 之 一 英寸 。 在 编写 程序 时 ， 请 确保 使 用 该 测量 单位 来 指定 页 面 上 的 元 素 大 小 。 
在 定位 绘制 的 元 素 时 ， 坐 标 系 的 原点 ( 即 (0,0) 点 ) 在 页 面 的 最 左上 角 。 
Tip : 虽然 Canvas 对 象 允许 我 们 将 打印 元 素 放 置 在 一 个 PDF 文档 的 边缘 ， 但 许多 打印 机 
无 法 在 纸张 的 边缘 打印 。 所 以 当 我 们 使 用 这 个 类 构建 一 个 打印 文档 时 ， 需 要 考虑 到 那些 
无 法 打印 的 边缘 区 域 。 


打印 自 定 义 文 档 
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Android 图 像 与 动画 


Android 图 像 与 动画 


编写 :kesenhoo - 原文 :http://developer.android.com/training/building-graphics.html 


这 些 课程 教 你 如 何 使 用 图 形 完成 任务 ， 这 会 使 你 的 app 在 竞争 中 占 优势 。 如 果 你 想 创建 超越 基 
本 用 户 界 面 的 漂亮 的 视觉 体验 ， 这 些 课程 会 帮助 你 做 到 。 


高 效 显示 Bitmap(Displaying Bitmaps Efficiently) - 官方 最 新 已 
经 移 除 的 章节 


如 何在 加 载 并 处 理 bitmaps 的 同时 保持 用 户 界面 响应 ， 防 止 超出 内 存 限制 。 


使 用 OpenGL ES 显示 图 像 (Displaying Graphics with OpenGL 
ES) 


如 何 使 用 Android app framework 绘 制 OpenGL 图 形 并 响应 触摸 。 


Animating Views Using Scenes and Transitions - 待 翻译 


How to animate state changes in a view hierarchy using transitions. 


As ha Zh = (Adding Animations) 


如 何 给 你 的 用 户 界面 添加 过 渡 动 画 。 
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高 效 显示 Bitmap 


编写 :kesenhoo - 原文 :http://developer.android.com/training/displaying- 
bitmaps/index.html 


这 一 章节 会 介绍 一 些 处 理 与 加 载 Bitmap 对 象 的 常用 方法 ， 这 些 技 术 能 够 使 得 程序 的 UI 不 会 被 
阻塞 ， 并 且 可 以 避免 程序 超出 内 存 限制 。 如 果 我 们 不 注意 这 些 ，Bitmaps 会 迅速 的 消耗 掉 可 用 
内 存 从 而 导致 程序 前 溃 ， 出 现下 面 的 异常 : java.1lang.0utofMemoryError: bitmap size exceeds 

VM budget. 


在 Android 应 用 中 加 载 Bitmaps 的 操作 是 需要 特别 小 心 处 理 的 ， 有 下 面 几 个 方面 的 原因 : 


e 移动 设备 的 系统 资源 有 限 。Android 设 备 对 于 单个 程序 至 少 需要 16MB 的 内 存 。Android 
Compatibility Definition Document (CDD), Section 3.7. Virtual Machine Compatibility 中 
给 出 了 对 于 不 同 大 小 与 密度 的 屏幕 的 最 低 内 存 需 求 。 应 用 应 该 在 这 个 最 低 内 存 限 制 下 去 
优化 程序 的 效率 。 当 然 ， 大 多 数 设 备 的 都 有 更 高 的 限制 需求 。 

Bitmap 会 消耗 很 多 内 存 ， 特 别 是 对 于 类 似 照 片 等 内 容 更 加 丰富 的 图 片 。 例 如 ，Galaxy 
Nexus 的 照相 机 能 够 拍摄 2592x1936 pixels (5 MB) 的 图 片 。 如 果 bitmap 的 图 像 配置 是 使 
用 ARGB 8888 (从 Android 2.3 开 始 的 默认 配置 ) ， 那 么 加 载 这 张 照片 到 内 存 大 约 需要 
19MB( 2592*1936*4 bytes) 的 空间 ， 从 而 迅速 消耗 掉 该 应 用 的 剩余 内 存 空间 。 
Android 应 用 的 UI 通 常会 在 一 次 操作 中 立即 加 载 许 多 张 bitmaps。 例如 在 ListView， 
GridView 与 ViewPager 等 控件 中 通常 会 需要 一 次 加 载 许 多 张 bitmaps， 而 且 需 要 预先 加 
载 一 些 没 有 在 屏幕 上 显示 的 内 容 ， 为 用 户 滑动 的 显示 做 准备 。 


e DEMO DisplayingBitmaps.zip 
e VEDIO : Bitmap Allocation 
e VEDIO : Making App Beautiful - Part 4 - Performance Tuning 


XL +H > Q 
Z P TRAE 
e 高 效 的 加 载 大 图 (Loading Large Bitmaps Efficiently) 
这 节 课 会 带领 你 学 习 如 何 解 析 很 大 的 Bitmaps 并 且 避 免 超 出 程序 的 内 存 限 制 。 
e 非 UI 线 程 处 理 Bitmap(Processing Bitmaps Off the UI Thread) 


处 理 Bitmap (RF > FRFR) 不 能 执行 在 主线 程 。 这 节 课 会 带领 你 学 习 如 何 使 用 
AsyncTask 在 后 台 线程 对 Bitmap 进 行 处 理 ， 并 解释 如 何 处 理 并 发 带 来 的 问题 。 


高 效 显 示 Bitmap 


。 缓存 Bitmaps(Caching Bitmaps) 


这 节 课 会 带领 你 学 习 如 何 使 用 内 存 与 磁盘 缓存 来 提升 加 载 多 张 Bitmaps 时 的 响应 速度 与 流 


畅 度 。 
。 管理 Bitmap 的 内 存 使 用 Managing Bitmap Memory) 

这 节 课 会 介绍 如 何 管理 Bitmap 的 内 存 占 用 ， 以 此 来 提升 程序 的 性 能 。 
e。 在 UI 上 显示 Bitmap(Displaying Bitmaps in Your UI) 


这 节 课 会 综合 之 前 章节 的 内 容 ， 演 示 如 何在 诸如 ViewPager 与 GridView 等 控件 中 使 用 后 侣 
线程 与 缓存 加 载 多 张 Bitmaps 。 


2 
— 
eo 


高 效 加 载 大 图 


编写 :kesenhoo - 原文 :http://developer.android.com/training/displaying-bitmaps/load- 
bitmap.html 


图 片 有 不 同 的 形状 与 大 小 。 在 大 多 数 情 况 下 它们 的 实际 大 小 都 比 需 要 呈现 的 尺寸 大 很 多 。 例 
如 ， 系 统 的 图 库 应 用 会 显示 那些 我 们 使 用 相机 拍摄 的 照片 ， 但 是 那些 图 片 的 分 辩 率 通常 都 比 
设备 屏幕 的 分 辨 率 要 高 很 多 。 


考虑 到 应 用 是 在 有 限 的 内 存 下 工作 的 ， 理 想 情况 是 我 们 只 需要 在 内 存 中 加 载 一 个 低 分 辩 率 的 
照片 即 可 。 为 了 更 便于 显示 ， 这 个 低 分 辨 率 的 照片 应 该 是 与 其 对 应 的 UI 控 件 大 小 相 匹配 的 。 
加 载 一 个 超过 屏幕 分 辩 率 的 高 分 辩 率 照片 不 仅 没有 任何 显而易见 的 好 处 ， 还 会 占用 宝贵 的 内 
存 资源 ， 另 外 在 快速 滑动 图 片 时 容易 产生 额外 的 效率 问题 。 


这 一 课 会 介绍 如 何 通 过 加 载 一 个 缩小 版 本 的 图 片 ， 从 而 避免 超出 程序 的 内 存 限 制 。 


读 取 位 图 的 尺寸 与 类 型 (Read Bitmap Dimensions 
and Type) 


BitmapFactory 提 供 了 一 些 解 码 (decode) 的 方法 (decodeByteArray(), decodeFile(), 
decodeResource() 等 ) ， 用 来 从 不 同 的 资源 中 创建 一 个 Bitmap。 我 们 应 该 根据 图 片 的 数据 源 
来 选择 合适 的 解码 方法 。 这 些 方法 在 构造 位 图 的 时 候 会 尝试 分 配 内 存 ， 因 此 会 容易 导 

致 outofMemory 的 异常 。 每 一 种 解码 方法 都 可 以 通过 BitmapFactory.Options 设 置 一 些 附 加 的 标 
记 ， 以 此 来 指定 解码 选项 。 设 置 inJustDecodeBounds 属性 为 true 可 以 在 解码 的 时 候 避 免 内 
存 的 分 配 ， 它 会 返回 一 个 null 的 Bitmap， 但 是 可 以 获取 到 outWidth, outHeight 与 
outMimeType。 该 技术 可 以 允许 你 在 构造 Bitmap 之 前 优先 读 图 片 的 尺寸 与 类 型 。 


BitmapFactory.Options options = new BitmapFactory.Options(); 
options.inJustDecodeBounds - true; 
BitmapFactory.decodeResource(getResources(), R.id.myimage, options); 
int imageHeight - options.outHeight; 

int imageWidth = options.outWidth; 

String imageType - options.outMimeType; 


为 了 避免 java.lang.OutofMemory 的 异常 ， 我 们 需要 在 站 正解 析 图 片 之 前 检查 它 的 尺寸 (除非 
你 能 确定 这 个 数据 源 提 供 了 准确 无 误 的 图 片 且 不 会 导致 占用 过 多 的 内 存 ) 。 


加 载 一 个 按 比 例 缩 小 的 版 本 到 内 存 中 (Load a 
Scaled Down Version into Memory) 


通过 上 面 的 步骤 我 们 已 经 获取 到 了 图 片 的 尺寸 ， 这 些 数据 可 以 用 来 帮助 我 们 决定 应 该 加 载 整 
个 图 片 到 内 存 中 还 是 加 载 一 个 缩小 的 版 本 。 有 下 面 一 些 因素 需要 考虑 : 


e 评估 加 载 完 整 图 片 所 需要 耗费 的 内 存 。 

e 程序 在 加 载 这 张 图 片 时 可 能 涉及 到 的 其 他 内 存 需 求 。 
e 呈现 这 张 图 片 的 控件 的 尺寸 大 小 。 

e 屏幕 大 小 与 当前 设备 的 屏幕 密度 。 


例如 ， 如 果 把 一 个 大 小 为 1024x768 像 素 的 图 片 显示 到 大 小 为 128x96 像 素 的 ImageView 上 吗 ， 
就 没有 必要 把 整 张 原 图 都 加 载 到 内 存 中 。 


为 了 告诉 解码 器 去 加 载 一 个 缩小 版 本 的 图 片 到 内 存 中 ， 需 要 在 BitmapFactory.Options 中 设置 
inSampleSize 的 值 。 例 如 , 一 个 分 辩 率 为 2048x1536 的 图 片 ， 如 果 设 置 inSampleSize 为 4， 
那么 会 产 出 一 个 大 约 512x384 大 小 的 Bitmap。 加 载 这 张 缩小 的 图 片 仅仅 使 用 大 概 0.75MB 的 内 
存 ， 如 果 是 加 载 完整 尺寸 的 图 片 ， 那 么 大 概 需要 花费 12MB (前 提 都 是 Bitmap 的 配置 是 
ARGB 8888) 。 下 面 有 一 段 根 据 目标 图 片 大 小 来 计算 Sample 图 片 大 小 的 代码 示例 : 


public static int calculateInSampleSize( 
BitmapFactory.Options options, int reqwidth, int reqHeight) { 
// Raw height and width of image 
final int height - options.outHeight; 
final int width = options.outWidth; 
int inSampleSize = 1; 


if (height > reqHeight || width > reqwidth) { 


final int halfHeight = height / 2; 
final int halfWidth = width / 2; 


// Calculate the largest inSampleSize value that is a power of 2 and keeps both 
// height and width larger than the requested height and width. 
while ((halfHeight / inSampleSize) > reqHeight 

&& (halfWidth / inSampleSize) > reqwidth) ( 


inSampleSize *= 2; 


} 


return inSampleSize; 








Note: 设置 inSampleSize 为 2 的 帘 是 因为 解码 器 最 终 还 是 会 对 非 2 的 暴 的 数 进行 向 下 处 
理 ， 获 取 到 最 靠近 2 的 宽 的 数 。 详 情 参 考 inSampleSize 的 文档 。 


为 了 使 用 该 方法 ， 首 先 需要 设置 inJustDecodeBounds A true , 把 options 的 值 传递 过 来 ， 然 
后 设置 inSampleSize 的 值 并 设置 inJustDecodeBounds 为 false ， 之 后 重新 调用 相关 的 解 
码 方 法 。 


public static Bitmap decodeSampledBitmapFromResource(Resources res, int resId, 
int reqwidth, int reqHeight) { 


// First decode with inJustDecodeBounds-true to check dimensions 
final BitmapFactory.Options options - new BitmapFactory.Options(); 
options.inJustDecodeBounds - true; 
BitmapFactory.decodeResource(res, resId, options); 


// Calculate inSampleSize 
options.inSampleSize = calculateInSampleSize(options, reqwidth, regHeight); 


// Decode bitmap with inSampleSize set 
options.inJustDecodeBounds - false; 
return BitmapFactory.decodeResource(res, resId, options); 


使 用 上 面 这 个 方法 可 以 简单 地 加 载 一 张 任 意 大 小 的 图 片 。 如 下 面 的 代码 样 例 显示 了 一 个 接近 
100x100 像 素 的 缩 略图 : 


mImageView. setImageBitmap( 
decodeSampledBitmapFromResource(getResources(), R.id.myimage, 100, 100)); 


我 们 可 以 通过 替换 合适 的 BitmapFactory.decode* 方法 来 实现 一 个 类 似 的 方法 ， 从 其 他 的 数据 
源 解析 Bitmap。 


非 UI 线 程 处 理 Bitmap 


编写 :kesenhoo - 原文 :http://developer.android.com/training/displaying-bitmaps/process- 
bitmap.html 
在 上 一 课 中 介绍 了 一 系列 的 BitmapFactory.decode* 方 法 ， 当 图 片 来 源 是 网 络 或 者 是 存储 卡 时 
(或 者 是 任何 不 在 内 存 中 的 形式 ) ， 这 些 方法 都 不 应 该 在 UI 线程 中 执行 。 因 为 在 上 述 情况 下 
加 载 数据 时 ， 其 执行 时 间 是 不 可 估计 的 ， 它 依赖 于 许多 因素 (从 网 络 或 者 存储 卡 读 取 数据 的 
速度 ， 图 片 的 大 小 ，CPU 的 速度 等 ) 。 如 果 其 中 任何 一 个 子 操作 阻塞 了 UI 线程 ， 系 统 都 会 容 
易 出 现 应 用 无 响应 的 错误 。 
这 一 节 课 会 介绍 如 何 使 用 AsyncTask 在 后 台 线 程 中 处 理 Bitmap 并 且 演 示 如 何 处 理 并 发 
(concurrency) 的 问题 。 


使 用 AsyncTask(Use a AsyncTask) 


AsyncTask 类 提供 了 一 个 在 后 台 线 程 执行 一 些 操 作 的 简单 方法 ， 它 还 可 以 把 后 台 的 执行 结果 
呈现 到 UI 线程 中 。 下 面 是 一 个 加 载 大 图 的 示例 : 


class BitmapWorkerTask extends AsyncTask { 
private final WeakReference imageViewReference; 
private int data - 0; 


public BitmapWorkerTask(ImageView imageView) { 
// Use a WeakReference to ensure the ImageView can be garbage collected 
imageViewReference - new WeakReference(imageView); 


} 

// Decode image in background. 

@Override 

protected Bitmap doInBackground(Integer... params) { 


data = params[0]; 
return decodeSampledBitmapFromResource(getResources(), data, 100, 100)); 


// Once complete, see if ImageView is still around and set bitmap. 
@Override 
protected void onPostExecute(Bitmap bitmap) { 
if (imageViewReference !- null && bitmap !- null) ( 
final ImageView imageView - imageViewReference.get(); 
if (imageView !- null) ( 
imageView.setImageBitmap(bitmap) ; 


为 ImageView 使 用 WeakReference 确 保 了 AsyncTask 所 引用 的 资源 可 以 被 垃圾 回收 器 回收 。 由 
于 当 任 务 结 束 时 不 能 确保 ImageView 仍 然 存 在 ， 因 此 我 们 必须 在 onPostExecute() 里 面 对 引 用 
进行 检查 。 该 ImageView 在 有 些 情况 下 可 能 已 经 不 存在 了 ， 例 如 ， 在 任务 结束 之 前 用 户 使 用 了 
回 退 操作 ， 或 者 是 配置 发 生 了 改变 (如 旋转 屏幕 等 ) 。 


开始 异步 加 载 位 图 ， 只 需要 创建 一 个 新 的 任务 并 执行 它 即 可 : 
public void loadBitmap(int resId, ImageView imageView) { 


BitmapWorkerTask task = new BitmapWorkerTask(imageView); 
task.execute(resId); 


处 理 并 发 问题 (Handle Concurrency) 


通常 类 似 ListView 与 GridView 等 视图 控件 在 使 用 上 面 演示 的 AsyncTask 方法 时 ， 会 同时 带 来 并 
发 的 问题 。 首 先 为 了 更 高 的 效率 ，ListView 与 GridView 的 子 ltem 视 图 会 在 用 户 滑动 屏幕 时 被 循 
环 使 用 。 如 果 每 一 个 子 视 图 都 触发 一 个 AsyncTask， 那 么 就 无 法 确保 关联 的 视图 在 结束 任务 


时 ， 分 配 的 视图 已 经 进入 循环 队列 中 ， 给 另外 一 个 子 视 图 进行 重用 。 而 有 全， 无 法 确保 所 有 的 
异步 任务 的 完成 顺序 和 他 们 本 身 的 启动 顺序 保持 一 致 。 


Multithreading for Performance 这 篇 博文 更 进一步 的 讨论 了 如 何 处 理 并 发 问题 ， 并 且 提 供 了 
一 种 解决 方法 : ImageView 保 存 最 近 使 用 的 AsyncTask 的 引用 ， 这 个 引用 可 以 在 任务 完成 的 时 
候 再 次 读 取 检 查 。 使 用 这 种 方式 , 就 可 以 对 前 面 提 到 的 AsyncTask 进 行 扩展 。 


创建 一 个 专用 的 Drawable 的 子 类 来 储存 任务 的 引用 。 在 这 种 情况 下 ， 我 们 使 用 了 一 
个 BitmapDrawable， 在 任务 执行 的 过 程 中 ， 一 个 占 位 图 片 会 显示 在 ImageView 中 : 


static class AsyncDrawable extends BitmapDrawable { 
private final WeakReference bitmapWorkerTaskReference; 


public AsyncDrawable(Resources res, Bitmap bitmap, 
BitmapWorkerTask bitmapWorkerTask) 1 
super(res, bitmap); 
bitmapWorkerTaskReference = 
new WeakReference(bitmapWorkerTask); 


public BitmapWorkerTask getBitmapWorkerTask() f 
return bitmapWorkerTaskReference.get(); 


在 执行 BitmapWorkerTask 之 前 ， 你 需要 创建 一 个 AsyncDrawable 并 且 将 它 绑 定 到 目标 控件 
ImageView 中 : 


public void loadBitmap(int resId, ImageView imageView) { 
if (cancelPotentialWork(resId, imageView)) { 
final BitmapWorkerTask task = new BitmapWorkerTask(imageView); 
final AsyncDrawable asyncDrawable - 
new AsyncDrawable(getResources(), mPlaceHolderBitmap, task); 
imageView.setImageDrawable(asyncDrawable) ; 
task.execute(resId); 


在 上 面 的 代码 示例 中 ， cancelPotentialwork 方法 检查 是 否 有 另 一 个 正在 执行 的 任务 与 该 
ImageView 关 联 了 起 来 ， 如 果 的 确 是 这 样 ， 它 通过 执行 cancel() 方法 来 取消 另 一 个 任务 。 在 
少数 情况 下 , 新 创建 的 任务 数据 可 能 会 与 已 经 存在 的 任务 相 吻 合 ， 这 样 的 话 就 不 需要 进行 下 一 
步 动 作 了 。 下 面 是 cancelPotentialwork 方法 的 实现 。 


public static boolean cancelPotentialWork(int data, ImageView imageView) { 
final BitmapWorkerTask bitmapWorkerTask - getBitmapWorkerTask(imageView); 


if (bitmapWorkerTask !- null) ( 

final int bitmapData - bitmapWorkerTask.data; 

if (bitmapData == 0 || bitmapData !- data) { 
// Cancel previous task 
bitmapWorkerTask.cancel(true); 

} else { 
// The same work is already in progress 
return false; 


} 


// No task associated with the ImageView, or an existing task was cancelled 
return true, 


在 上 面 的 代码 中 有 一 个 辅助 方法 : getBitmapworkerTask() ， 它 被 用 作 检 索 AsyncTask 是 否 已 
经 被 分 配 到 指定 的 ImageView: 


private static BitmapWorkerTask getBitmapWorkerTask(ImageView imageView) { 
if (imageView != null) { 
final Drawable drawable - imageView.getDrawable(); 
if (drawable instanceof AsyncDrawable) { 
final AsyncDrawable asyncDrawable = (AsyncDrawable) drawable; 
return asyncDrawable.getBitmapWorkerTask(); 


} 


return null; 


最 后 一 步 是 在 BitmapWorkerTask 的 onPostExecute() 方法 里 面 做 更 新 操作 : 


class BitmapWorkerTask extends AsyncTask { 


@Override 
protected void onPostExecute(Bitmap bitmap) { 
if (isCancelled()) { 
bitmap = null; 


if (imageViewReference != null && bitmap != null) { 
final ImageView imageView = imageViewReference.get(); 
final BitmapWorkerTask bitmapWorkerTask = 
getBitmapWorkerTask(imageView); 
if (this -- bitmapWorkerTask && imageView !- null) ( 
imageView.setiImageBitmap(bitmap); 


这 个 方法 不 仅仅 适用 于 ListView 与 GridView 控 件 ， 在 那些 需要 循环 利用 子 视 图 的 控件 中 同样 适 
用 : 只 需要 在 设置 图 片 到 ImageView 的 地 方 调用 loadBitmap 方法 。 例 如 ， 在 GridView 中 实现 
这 个 方法 可 以 在 getView() 中 调用 。 


2% 5 Bitmap 


编写 :kesenhoo - Æ X:http://developer.android.com/training/displaying-bitmaps/cache- 
bitmap.html 


将 单个 Bitmap 加 载 到 UI 是 简单 直接 的 ， 但 是 如 果 我 们 需要 一 次 性 加 载 大量 的 图 片 ， 事 情 则 会 
变 得 复杂 起 来 。 在 大 多 数 情况 下 (例如 在 使 用 ListView，GridView 或 ViewPager 时 ) ， 屏 幕 上 
的 图 片 和 因 滑 动 将 要 显示 的 图 片 的 数量 通常 是 没有 限制 的 。 


通过 循环 利用 子 视图 可 以 缕 解 内 存 的 使 用 ， 垃 圾 回收 器 也 会 释放 那些 不 再 需要 使 用 的 
Bitmap。 这 些 机 制 都 非常 好 ， 但 是 为 了 保证 一 个 流畅 的 用 户 体 验 ， 我 们 希望 避免 在 每 次 屏幕 
滑动 回来 时 ， 都 要 重复 处 理 那 些 图 片 。 内 存 与 磁盘 缓存 通常 可 以 起 到 辅助 作用 ， 允 许 控件 可 
以 快速 地 重新 加 载 那 些 处 理 过 的 图 片 。 


这 一 课 会 介绍 在 加 载 多 张 Bitmap 时 使 用 内 存 缓存 与 磁盘 缓存 来 提高 响应 速度 与 UI 流 息 度 。 


使 用 内 存 缓 存 (Use a Memory Cache) 


内 存 缓 存 以 花费 宝贵 的 程序 内 存 为 前 提 来 快速 访问 位 图 。LruCache 类 【在 API Level 4 的 

Support Library 中 也 可 以 找到 ) 特别 适合 用 来 缓存 Bitmaps， 它 使 用 一 个 强 引 用 (strong 

referenced) 的 LinkedHashMap 保 存 最 近 引 用 的 对 象 ， 并 且 在 缓存 超出 设置 大 小 的 时 候 别 除 
(evict) 最 近 最 少 使 用 到 的 对 象 。 


Note: 在 过 去 ， 一 种 比较 流行 的 内 存 缓 存 实 现 方法 是 使 用 软 引 用 (SoftReference) 或 弱 
引用 (WeakReference) 对 Bitmap 进 行 缓存 ， 然 而 我 们 并 不 推荐 这 样 的 做 法 。 从 Android 
2.3 (API Level 9) 开 始 ， 垃 圾 回收 机 制 变 得 更 加 频繁 ， 这 使 得 释放 软 ( 弱 ) 引用 的 频率 也 
随 之 增高 ， 导 致使 用 引用 的 效率 降低 很 多 。 而 且 在 Android 3.0 (API Level 11) 之 前 ， 备 份 
的 Bitmap 会 存放 在 Native Memory 中 ， 它 不 是 以 可 预知 的 方式 被 释放 的 ， 这 样 可 能 导致 
程序 超出 它 的 内 存 限制 而 前 溃 。 


为 了 给 LruCache 选 择 一 个 合适 的 大 小 ， 需 要 考虑 到 下 面 一 些 因素 : 


e 应 用 剩 下 了 多 少 可 用 的 内 存 ? 

e 多 少 张 图 片 会 同时 呈现 到 屏幕 上 ? 有 多 少 图 片 需要 准备 好 以 便 马 上 显示 到 屏幕 了 

e 设备 的 屏幕 大 小 与 密度 是 多 少 ? 一 个 具有 特别 高 密度 屏幕 (xhdpi) 的 设备 ， 像 Galaxy 
Nexus 会 比 Nexus S (hdpi) 需要 一 个 更 大 的 缓存 空间 来 缓存 同样 数量 的 图 片 。 
Bitmap 的 尺寸 与 配置 是 多 少 ， 会 花费 多 少 内 存 ? 

图 片 被 访问 的 频率 如 何 ? 是 其 中 一 些 比 另 外 的 访问 更 加 频繁 吗 ? 如 果 是 ， 那 么 我 们 可 能 
希望 在 内 存 中 保存 那些 最 常 访问 的 图 片 ， 或 者 根据 访问 频率 给 Bitmap 分 组 ， 为 不 同 的 
Bitmap 组 设置 多 个 LruCache 对 象 。 


e 是 否 可 以 在 缓存 图 片 的 质量 与 数量 之 间 寻 找平 衡 点 ? 某 些 时 候 保 存 大 量 低 质量 的 Bitmap 
会 非常 有 用 ， 加 载 更 高 质量 图 片 的 任务 可 以 交 给 另外 一 个 后 台 线 程 。 


通常 没有 指定 的 大 小 或 者 公式 能 够 适用 于 所 有 的 情形 ， 我 们 需要 分 析 实 际 的 使 用 情况 后 ， 提 
出 一 个 合适 的 解决 方案 。 缓 存 太 小 会 导致 额外 的 花 销 却 没 有 明显 的 好 处 ， 缓 存 太 大 同样 会 导 
致 java.lang.OutOfMemory 的 异常 ， 并 且 使 得 你 的 程序 只 留 下 小 部 分 的 内 存 用 来 工作 〈 缓 存 占 
用 太 多 内 存 ， 导 致 其 他 操作 会 因为 内 存 不 够 而 抛 出 异常 ) 。 


下 面 是 一 个 为 Bitmap 建 立 LruCache 的 示例 : 


private LruCache<String, Bitmap» mMemoryCache; 


@Override 
protected void onCreate(Bundle savedInstanceState) { 


// Get max available VM memory, exceeding this amount will throw an 
// OutOfMemory exception. Stored in kilobytes as LruCache takes an 

// int in its constructor. 

final int maxMemory - (int) (Runtime.getRuntime().maxMemory() / 1024); 


// Use 1/8th of the available memory for this memory cache. 
final int cacheSize - maxMemory / 8; 


mMemoryCache = new LruCache<String, Bitmap>(cacheSize) ( 
@Override 
protected int sizeOf(String key, Bitmap bitmap) { 
// The cache size will be measured in kilobytes rather than 
// number of items. 
return bitmap.getByteCount() / 1024; 


un 


public void addBitmapToMemoryCache(String key, Bitmap bitmap) { 
if (getBitmapFromMemCache(key) == null) { 
mMemoryCache.put(key, bitmap); 


public Bitmap getBitmapFromMemCache(String key) { 
return mMemoryCache.get(key); 


Note: 在 上 面 的 例子 中 , 有 1/8 的 内 存 空 间 被 用 作 缓 存 。 这 意味 着 在 常见 的 设备 上 
(hdpi) ， 最 少 大 概 有 4MB 的 缓存 空间 (32/8) 。 如 果 一 个 卉 满 图 片 的 GridView 控 件 放 
置 在 800x480 像 素 的 手机 屏幕 上 ， 大 概 会 花费 1.5MB 的 缓存 空间 (800x480x4 bytes) > 
因此 缓存 的 容量 大 概 可 以 缓存 2.5 页 的 图 片 内 容 。 


NO 
IN 


当 加 载 Bitmap 显 示 到 |ImageView 之 前 ， 会 先 从 LruCache 中 检查 是 否 存 在 这 个 Bitmap。 如 果 
确实 存在 ， 它 会 立即 被 用 来 显示 到 ImageView 上 ， 如 果 没 有 找到 ， 会 触发 一 个 后 台 线程 去 处 理 


显示 该 Bitmap 任 务 。 
public void loadBitmap(int resId, ImageView imageView) { 
final String imageKey - String.valueOf(resId); 


final Bitmap bitmap - getBitmapFromMemCache(imageKey); 
if (bitmap != null) { 
mImageView. setImageBitmap(bitmap) ; 


) else { 
mImageView.setImageResource(R.drawable.image placeholder); 


BitmapWorkerTask task - new BitmapWorkerTask(mImageView); 


task.execute(resId); 


上 面 的 程序 中 Bitmapworkerrask 需要 把 解析 好 的 Bitmap 添 加 到 内 存 缓存 中 : 


class BitmapWorkerTask extends AsyncTask«Integer, Void, Bitmap» { 


// Decode image in background. 
@Override 
protected Bitmap doInBackground(Integer... params) { 
final Bitmap bitmap = decodeSampledBitmapFromResource( 


getResources(), params[0], 100, 100)); 
addBitmapToMemoryCache(String.valueOf(params[0]), bitmap); 


return bitmap; 


使 用 磁盘 缓存 (Use a Disk Cache) 


内 存 缓存 能 够 提高 访问 最 近 用 过 的 Bitmap 的 速度 ， 但 是 我 们 无 法 保证 最 近 访 问 过 的 Bitmap 都 
能 够 保存 在 缓存 中 。 像 类 似 GridView 等 需要 大 量 数据 填充 的 控件 很 容易 就 会 用 尽 整 个 内 存 缓 
存 。 另 外 ， 我 们 的 应 用 可 能 会 被 类 似 打 电话 等 行为 而 暂停 并 退 到 后 台 ， 因 为 后 台 应 用 可 能 会 
被 杀 死 ， 那 么 内 存 缓存 就 会 被 销毁 ， 里 面 的 Bitmap 也 就 不 存在 了 。 一 旦 用 户 恢复 应 用 的 状 
态 ， 那 么 应 用 就 需要 重新 处 理 那 些 图 片 。 


磁盘 缓存 可 以 用 来 保存 那些 已 经 处 理 过 的 Bitmap， 它 还 可 以 减少 那些 不 再 内 存 缓存 中 的 
Bitmap 的 加 载 次 数 。 当 然 从 磁盘 读 取 图 片 会 比 从 内 存 要 慢 ， 而 且 由 于 磁盘 读 取 操作 时 间 是 不 
可 预期 的 ， 读 取 操 作 需 要 在 后 人 台 线 程 中 处 理 。 


rr 
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Note: 如 果 图 片 会 被 更 频繁 的 访问 ， 使 用 ContentProvider 或 许 会 更 加 合适 ， 比 如 在 图 库 应 


用 中 。 


这 一 节 的 范例 代码 中 使 用 了 一 个 从 Android 源 码 中 剥离 出 来 的 DiskLrucache 。 改 进 过 的 范例 代 


码 在 已 有 内 存 缓存 的 基础 上 增加 磁盘 缓存 的 功能 。 


private DiskLruCache mDiskLruCache; 

private final Object mDiskCacheLock = new Object(); 

private boolean mDiskCacheStarting = true; 

private static final int DISK_CACHE_SIZE = 1024 * 1024 * 10; // 10MB 
private static final String DISK_CACHE_SUBDIR = "thumbnails"; 


@Override 
protected void onCreate(Bundle savedInstanceState) { 


// Initialize memory cache 


// Initialize disk cache on background thread 
File cacheDir - getDiskCacheDir(this, DISK CACHE SUBDIR); 
new InitDiskCacheTask().execute(cacheDir); 


class InitDiskCacheTask extends AsyncTask«File, Void, Void» { 
@Override 
protected Void doInBackground(File... params) { 
synchronized (mDiskCacheLock) { 
File cacheDir = params[0]; 
mDiskLruCache = DiskLruCache.open(cacheDir, DISK CACHE SIZE); 
mDiskCacheStarting = false; // Finished initialization 
mDiskCacheLock.notifyAll(); // Wake any waiting threads 
} 


return null; 


class BitmapWorkerTask extends AsyncTask«Integer, Void, Bitmap» { 


// Decode image in background. 

@Override 

protected Bitmap doInBackground(Integer... params) { 
final String imageKey = String.valueOf(params[0]); 


// Check disk cache in background thread 
Bitmap bitmap = getBitmapFromDiskCache(imageKey ) ; 


if (bitmap == null) { // Not found in disk cache 
// Process as normal 
final Bitmap bitmap = decodeSampledBitmapFromResource( 
getResources(), params[0], 100, 100)); 


NO 


NO 


NO 


// Add final bitmap to caches 
addBitmapToCache(imageKey, bitmap); 


return bitmap; 


public void addBitmapToCache(String key, Bitmap bitmap) { 
// Add to memory cache as before 
if (getBitmapFromMemCache(key) == null) { 
mMemoryCache.put(key, bitmap); 


// Also add to disk cache 
synchronized (mDiskCacheLock) { 
if (mDiskLruCache !- null && mDiskLruCache.get(key) -- null) ( 
mDiskLruCache.put(key, bitmap); 


public Bitmap getBitmapFromDiskCache(String key) { 
synchronized (mDiskCacheLock) { 
// Wait while disk cache is started from background thread 
while (mDiskCacheStarting) ( 
try { 
mDiskCacheLock.wait(); 
} catch (InterruptedException e) {} 
} 
if (mDiskLruCache != null) { 
return mDiskLruCache.get(key); 


} 


return null; 


// Creates a unique subdirectory of the designated app cache directory. Tries to use e 
xternal 
// but if not mounted, falls back on internal storage. 
public static File getDiskCacheDir (Context context, String uniqueName) { 
// Check if media is mounted or storage is built-in, if so, try and use external c 
ache dir 
// otherwise use internal cache dir 
final String cachePath = 
Environment.MEDIA MOUNTED.equals(Environment.getExternalStorageState()) || 
!isExternalStorageRemovable() ? getExternalCacheDir(context).getPa 
th() 
context.getCacheDir().getPath(); 


return new File(cachePath + File.separator + uniqueName) ; 


NO 
NO 


Note: 因 为 初始 化 磁盘 缓存 涉及 到 1/O 操 作 ， 所 以 它 不 应 该 在 主线 程 中 进行 。 但 是 这 也 意 
ee a ee E 一 在 
锁 对 象 (lock object) 来 确保 在 磁盘 缓存 完成 初始 化 之 前 ， 应 用 无 法 对 它 进 行 读 取 。 


内 存 缓存 的 检查 是 可 以 在 UI 线程 中 进行 的 ， 磁 盘 缓 存 的 检查 需要 在 后 台 线 程 中 处 理 。 磁 盘 操 
作 永 远 都 不 应 该 在 UI 线 程 中 发 生 。 当 图 片 处 理 完 成 后 ，Bitmap 需 要 添加 到 内 存 缓存 与 磁盘 缓 
存 中 ， 方 便 之 后 的 使 用 。 


处 理 配 置 改变 (Handle Configuration Changes) 


如 果 运 行 时 设备 配置 信息 发 生 改 变 ， 例 如 屏幕 方向 的 改变 会 导致 Android 中 当前 显示 的 Activity 
先 被 销毁 然后 重 店 。 (关于 这 一 方面 的 更 多 信息 ， 请 参考 Handling Runtime Changes) 。 我 
们 需要 在 配置 改变 时 避免 重新 处 理 所 有 的 图 片 ， 这 样 才能 提供 给 用 户 一 个 良好 的 平滑 过 度 的 
体验 。 


幸运 的 是 ， 在 前 面 介 绍 使 用 内 存 缓存 的 部 分 ， 我 们 已 经 知道 了 如 何 建立 内 存 缓 存 。 这 个 缓存 
可 以 通过 调用 setRetainlnstance(true)) 保 留 a nei a 的 方法 把 缓存 传递 给 新 的 
Activity。 在 这 个 Activity 被 重新 创建 之 后 ， 这 个 保留 的 Fragment 会 被 重新 附着 上 。 这 样 你 就 可 
以 访问 缓存 对 象 了 ， 从 缓存 中 获取 到 图 片 信息 并 快速 的 重新 显示 到 ImageView 上 。 


下 面 是 配置 改变 时 使 用 Fragment 来 保留 LruCache 的 代码 示例 : 


private LruCache<String, Bitmap> mMemoryCache; 


@Override 
protected void onCreate(Bundle savedInstanceState) { 


RetainFragment retainFragment = 
RetainFragment.findOrCreateRetainFragment (getFragmentManager()); 
mMemoryCache - retainFragment.mRetainedCache; 
if (mMemoryCache == null) { 
mMemoryCache = new LruCache<String, Bitmap>(cacheSize) { 
// Initialize cache here as usual 


} 


retainFragment.mRetainedCache = mMemoryCache; 


class RetainFragment extends Fragment { 
private static final String TAG = "RetainFragment"; 
public LruCache<String, Bitmap» mRetainedCache; 


public RetainFragment() {} 


public static RetainFragment findOrCreateRetainFragment(FragmentManager fm) { 
RetainFragment fragment - (RetainFragment) fm.findFragmentByTag(TAG); 
if (fragment == null) { 
fragment - new RetainFragment(); 
fm.beginTransaction().add(fragment, TAG).commit(); 


} 

return fragment; 
} 
@Override 


public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setRetainInstance(true); 


为 了 测试 上 面 的 效果 ， 可 以 尝试 在 保留 Fragment 与 没有 这 样 做 的 情况 下 旋转 屏幕 。 我 们 会 发 
现 当 保留 缓存 时 ， 从 内 存 缓 存 中 重新 绘制 几乎 没有 延迟 的 现象 。 内存 缓存 中 没有 的 图 片 可 能 
存储 在 磁盘 缓存 中 。 如 果 两 个 缓存 中 都 没有 ， 则 图 像 会 像 平时 正常 流程 一 样 被 处 理 。 


管理 Bitmap 的 内 存 使 用 


编写 :kesenhoo - 原文 :http://developer.android.com/training/displaying-bitmaps/manage- 
memory.html 


这 节 课 将 作为 缓存 Bitmaps 课 程 的 进一步 延伸 。 为 了 优化 垃圾 回收 机 制 与 Bitmap 的 重用 ， 我 们 
还 有 一 些 特定 的 事情 可 以 做 。 同时 根据 Android 的 不 同 版 本 ， 推 荐 的 策略 会 有 所 差 

异 。DisplayingBitmaps 的 示例 程序 会 演示 如 何 设计 我 们 的 程序 ， 使 得 它 能 够 在 不 同 的 Android 
平台 上 高 效 地 运行 . 

为 了 给 这 节 课 黄 定 基础 ， 我 们 首先 要 知道 Android 管 理 Bitmap 内 存 使 用 的 演变 进程 : 

e Android 2.2 (API level 8) 以 及 之 前 ， 当 垃圾 回收 发 生 时 ， 应 用 的 线程 是 会 被 暂停 的 ， 这 
会 导致 一 个 延迟 滞后 ， 并 降低 系统 效率 。 从 Android 2.3 开 始 ， 添 加 了 并 发 垃圾 回收 的 机 
制 ， 这 意味 着 在 一 个 Bitmap 不 再 被 引用 之 后 ， 它 所 占用 的 内 存 会 被 立即 回收 。 

在 Android 2.3.3 (API level 10) 以 及 之 前 , 一 个 Bitmap 的 像素 级 数据 〈pixel data) 是 存放 
在 Native 内 存 空间 中 的 。 这 些 数据 与 Bitmap 本 身 是 隔离 的 ，Bitmap 本 身 被 存放 在 Dalvik 
堆 中 。 我 们 无 法 预测 在 Native 内 存 中 的 像素 级 数据 何 时 会 被 释放 ， 这 意味 着 程序 容易 超过 
它 的 内 存 限制 并 且 崩 溃 。 B Android 3.0 (API Level 11) 开 始 ， 像 素 级 数据 则 是 与 
Bitmap 本 身 一 起 存放 在 Dalvik 扒 中。 


下 面 会 介绍 如 何在 不 同 的 Android 版 本 上 优化 Bitmap 内 存 使 用 。 


管理 Android 2.3.3 及 以 下 版 本 的 内 存 使 用 


在 Android 2.3.3 (API level 10) 以 及 更 低 版 本 上 ， 推 荐 使 用 recycle() 方 法 。 如 果 在 应 用 中 显示 
了 大 量 的 Bitmap 数 据 ， 我 们 很 可 能 会 遇 到 OutOfMemoryError 的 错误 。 recycle() 方 法 可 以 使 得 
程序 更 快 的 释放 内 存 。 


Caution : 只 有 当 我 们 确定 这 个 Bitmap 不 再 需要 用 到 的 时 候 才 应 该 使 用 recycle()。 在 执行 
recycle() 方 法 之 后 ， 如 果 尝 试 绘制 这 个 Bitmap > 我 们 将 得 到 "canvas: trying to use a 


recycled bitmap" 的 错误 提示 。 
下 面 的 代码 片段 演示 了 使 用 recycle) 的 例子 。 它 使 用 了 引用 计数 的 方法 


( mDisplayRefCount 与 mcacheRefcount ) 来 追踪 一 个 Bitmap 目 前 是 否 有 被 显示 或 者 是 在 缓存 
中 。 并 且 在 下 面 列举 的 条 件 满足 时 ， 回 收 Bitmap : 


* mDisplayRefCount 与 mCacheRefCount 的 引用 计数 均 为 0; 
e bitmap 不 为 null , 并 且 它 还 没有 被 回收 。 


private int mCacheRefCount = 0; 
private int mDisplayRefCount - 0; 


// Notify the drawable that the displayed state has changed. 
// Keep a count to determine when the drawable is no longer displayed. 
public void setIsDisplayed(boolean isDisplayed) { 
synchronized (this) { 
if (isDisplayed) { 
mDisplayRefCount++; 
mHasBeenDisplayed = true; 
} else { 
mDisplayRefCount--; 


} 


// Check to see if recycle() can be called. 
checkState(); 


// Notify the drawable that the cache state has changed. 
// Keep a count to determine when the drawable is no longer being cached. 
public void setIsCached(boolean isCached) { 
synchronized (this) { 
if (isCached) { 
mCacheRefCount++; 
} else { 
mCacheRefCount - - ; 


} 


// Check to see if recycle() can be called. 
checkState(); 


private synchronized void checkState() { 
// If the drawable cache and display ref counts = 0, and this drawable 
// has been displayed, then recycle. 
if (mCacheRefCount «- 0 && mDisplayRefCount «- 0 && mHasBeenDisplayed 
&& hasValidBitmap()) { 
getBitmap().recycle(); 


private synchronized boolean hasValidBitmap() { 
Bitmap bitmap - getBitmap(); 
return bitmap !- null && !bitmap.isRecycled(); 


® Android 3.0 及 其 以 上 版 本 的 内 存 


NO 


NO 


从 Android 3.0 (API Level 11) 开 始 ， 引 进 了 BitmapFactory.Options.inBitmap 字 段 。 如 果 使 用 
了 这 个 设置 字段 ，decode 方 法 会 在 加 载 Bitmap 数 据 的 时 候 去 重用 已 经 存在 的 Bitmap。 这 意 
着 Bitmap 的 内 存 是 被 重新 利用 的 ， 这 样 可 以 提升 性 能 ， 并 且 减 少 了 内 存 的 分 配 与 回收 。 然 

而 ， 使 用 inBitmap 有 一 些 限制 ， 特 别 是 在 Android 4.4 (API level 19) 之 前 ， 只 有 同等 大 小 的 位 
图 才 可 以 被 重用 。 详 情 请 查看 inBitmap 文 档 。 


保存 Bitmap 供 以 后 使 用 


下 面 演 示 了 如 何 将 一 个 已 经 存在 的 Bitmap 存 放 起 来 以 便 后 续 使 用 。 当 一 个 应 用 运行 在 Android 
3.0 或 者 更 高 的 平台 上 并 且 Bitmap 从 LruCache 中 移 除 时 ，Bitmap 的 一 个 软 引 用 会 被 存放 
在 Hashset 中 ， 这 样 便于 之 后 可 能 被 inBitmap 重 用 : 


Set<SoftReference<Bitmap>> mReusableBitmaps; 
private LruCache<String, BitmapDrawable» mMemoryCache; 


// If you're running on Honeycomb or newer, create a 
// synchronized HashSet of references to reusable bitmaps. 
if (Utils.hasHoneycomb()) { 
mReusableBitmaps - 
Collections.synchronizedSet(new HashSet<SoftReference<Bitmap>>()); 


mMemoryCache = new LruCache<String, BitmapDrawable>(mCacheParams.memCacheSize) { 


// Notify the removed entry that is no longer being cached. 
@Override 
protected void entryRemoved(boolean evicted, String key, 
BitmapDrawable oldValue, BitmapDrawable newValue) { 
if (RecyclingBitmapDrawable.class.isInstance(oldValue)) ( 
// The removed entry is a recycling drawable, so notify it 
// that it has been removed from the memory cache. 
((RecyclingBitmapDrawable) oldValue).setIsCached(false); 
} else { 
// The removed entry is a standard BitmapDrawable. 
if (Utils.hasHoneycomb()) { 
// We're running on Honeycomb or later, so add the bitmap 
// to a SoftReference set for possible use with inBitmap later. 
mReusableBitmaps.add 
(new SoftReference<Bitmap>(oldValue.getBitmap())); 


使 用 已 经 存在 的 Bitmap 


在 运行 的 程序 中 ，decode 方 法 会 检查 看 是 否 存在 可 重用 的 Bitmap。 例如 : 


public static Bitmap decodeSampledBitmapFromFile(String filename, 
int reqwidth, int regHeight, ImageCache cache) { 


final BitmapFactory.Options options - new BitmapFactory.Options(); 
BitmapFactory.decodeFile(filename, options); 
// If we're running on Honeycomb or newer, try to use inBitmap. 


if (Utils.hasHoneycomb()) { 
addInBitmapOptions(options, cache); 


return BitmapFactory.decodeFile(filename, options); 


下 面 的 代码 是 上 述 代 码 片 段 中 ， addrnBitmapoptions() 方法 的 具体 实现 。 它 会 为 inBitmap 查 
找 一 个 已 经 存在 的 Bitmap， 并 将 它 设 置 为 inBitmap 的 值 。 注 意 这 个 方法 只 有 在 找到 合适 且 可 
重用 的 Bitmap 时 才 会 赋值 给 inBitmap (我 们 需要 在 赋值 之 前 进行 检查 ) 


hh 
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private static void addInBitmapOptions(BitmapFactory.Options options, 
ImageCache cache) { 
// inBitmap only works with mutable bitmaps, so force the decoder to 
// return mutable bitmaps. 
options.inMutable - true; 


if (cache != null) { 
// Try to find a bitmap to use for inBitmap. 
Bitmap inBitmap - cache.getBitmapFromReusableSet(options); 


if (inBitmap != null) { 
// If a suitable bitmap has been found, set it as the value of 
// inBitmap. 
options.inBitmap - inBitmap; 


// This method iterates through the reusable bitmaps, looking for one 

// to use for inBitmap: 

protected Bitmap getBitmapFromReusableSet(BitmapFactory.Options options) { 
Bitmap bitmap - null; 


if (mReusableBitmaps != null && !mReusableBitmaps.isEmpty()) { 
synchronized (mReusableBitmaps) { 
final Iterator<SoftReference<Bitmap>> iterator 
= mReusableBitmaps.iterator(); 
Bitmap item; 


while (iterator.hasNext()) { 
item = iterator.next().get(); 


if (null != item && item.isMutable()) { 
// Check to see it the item can be used for inBitmap. 
if (canUseForInBitmap(item, options)) { 
bitmap - item; 


// Remove from reusable set so it can't be used again. 
iterator.remove(); 
break; 
} 
} else f 
// Remove from the set if the reference has been cleared. 
iterator.remove(); 


} 


return bitmap; 


ş 
J 
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最 后 ， 下 面 这 个 方法 判断 候选 Bitmap 是 否 满足 inBitmap 的 大 小 条 件 : 


static boolean canUseForInBitmap( 
Bitmap candidate, BitmapFactory.Options targetOptions) ( 


if (Build.VERSION.SDK INT >= Build.VERSION CODES.KITKAT) { 
// From Android 4.4 (KitKat) onward we can re-use if the byte size of 
// the new bitmap is smaller than the reusable bitmap candidate 
// allocation byte count. 
int width - targetOptions.outWidth / targetOptions.inSampleSize; 
int height - targetOptions.outHeight / targetOptions.inSampleSize; 
int byteCount - width * height * getBytesPerPixel(candidate.getConfig()); 
return byteCount «- candidate.getAllocationByteCount(); 


// On earlier versions, the dimensions must match exactly and the inSampleSize mus 
t be i 
return candidate.getWidth() == targetOptions.outWidth 
&& candidate.getHeight() == targetOptions.outHeight 
&& targetOptions.inSampleSize == 1; 


Jee 
* A helper function to return the byte usage per pixel of a bitmap based on its confi 
guration. 
yf 
static int getBytesPerPixel(Config config) { 
if (config == Config.ARGB_8888) { 
rebum 
} else if (config == Config.RGB 565) { 
return 2; 
) else if (config == Config.ARGB 4444) { 
return 2; 
} else if (config == Config.ALPHA_8) { 
(etum 


} 


return i; 


在 UI 上 显示 Bitmap 


编写 :kesenhoo - 原文 :http://developer.android.com/training/displaying-bitmaps/display- 
bitmap.html 


这 一 课 会 演示 如 何 运 用 前 面 几 节 课 的 内 容 ， 使 用 后 台 线 程 与 缓存 机 制 将 图 片 加载 到 ViewPager 
与 GridView 控 件 ， 并 且 学 习 处 理 并 发 与 配置 改变 问题 。 


实现 加 载 图 片 到 ViewPager 


Swipe View Pattern 是 一 个 使 用 滑动 来 切换 显示 不 同 详情 页 面 的 设计 模型 。 (关于 这 种 效果 请 
先 参看 Android Design: Swipe Views) 。 我 们 可 以 通过 PagerAdapter 与 ViewPager 控 件 来 实 
现 这 个 效果 。 不 过 ， 一 个 更 加 合适 的 Adapter 是 PagerAdapter 的 一 个 子 类 ， 叫 

做 FragmentStatePagerAdapter : 它 可 以 在 茶 个 ViewPager 中 的 子 视图 切换 出 屏幕 时 自动 销 奴 
与 保存 Fragments 的 状态 。 这 样 能 够 保持 更 少 的 内 存 消耗 。 


Note: 如 果 只 有 为 数 不 多 的 图 片 并 且 确 保 不 会 超出 程序 内 存 限制 ， 那 么 使 用 
PagerAdapter 或 FragmentPagerAdapter 会 更 加 合适 。 


下 面 是 一 个 使 用 ViewPager 与 ImageView 作 为 子 视图 的 示例 。 主 Activity 包 含有 ViewPager 和 
Adapter ° 


public class ImageDetailActivity extends FragmentActivity { 
public static final String EXTRA IMAGE - "extra image"; 


private ImagePagerAdapter mAdapter; 
private ViewPager mPager; 


// A static dataset to back the ViewPager adapter 
public final static Integer[] imageResIds = new Integer[] { 
R.drawable.sample image 1, R.drawable.sample image 2, R.drawable.sample im 


age 3, 
R.drawable.sample image 4, R.drawable.sample image 5, R.drawable.sample im 
age 6, 
R.drawable.sample image 7, R.drawable.sample image 8, R.drawable.sample im 
age 93; 
@Override 


public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.image detail pager); // Contains just a ViewPager 


mAdapter - new ImagePagerAdapter(getSupportFragmentManager(), imageResIds.leng 
th); 

mPager - (ViewPager) findViewById(R.id.pager); 

mPager.setAdapter(mAdapter); 


public static class ImagePagerAdapter extends FragmentStatePagerAdapter { 
private final int mSize; 


public ImagePagerAdapter(FragmentManager fm, int size) { 
super(fm); 
mSize - size; 


@Override 
public int getCount() { 
return mSize; 


@Override 
public Fragment getItem(int position) { 
return ImageDetailFragment .newInstance(position) ; 


Fragment €. &, T ImageView4Z£ ff: 


public class ImageDetailFragment extends Fragment { 
private static final String IMAGE DATA EXTRA = "resId"; 
private int mImageNum; 
private ImageView mImageView; 


static ImageDetailFragment newInstance(int imageNum) { 
final ImageDetailFragment f - new ImageDetailFragment(); 
final Bundle args - new Bundle(); 
args.putInt(IMAGE DATA EXTRA, imageNum); 
f.setArguments(args); 
return f; 


// Empty constructor, required as per Fragment docs 
public ImageDetailFragment() {} 


@Override 

public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
mImageNum = getArguments() != null ? getArguments().getInt(IMAGE DATA EXTRA) 


@Override 
public View onCreateView(LayoutInflater inflater, ViewGroup container, 
Bundle savedInstanceState) { 
// image detail fragment.xml contains just an ImageView 
final View v - inflater.inflate(R.layout.image detail fragment, container, fal 


se); 
mImageView = (ImageView) v.findViewById(R.id.imageView); 
return v; 
^ 
@Override 


public void onActivityCreated(Bundle savedInstanceState) { 
super.onActivityCreated(savedInstanceState) ; 
final int resId = ImageDetailActivity.imageResIds[mImageNum]; 
mImageView.setImageResource(resId); // Load image into ImageView 


希望 你 有 发 现 上 面 示例 存在 的 问题 : 在 UI 线程 中 读 取 图 片 可 能 会 导致 应 用 无 响应 。 因 此 使 用 
在 第 二 课 中 学 习 的 AsyncTask 会 更 好 。 


public class ImageDetailActivity extends FragmentActivity { 


public void loadBitmap(int resId, ImageView imageView) { 
mImageView.setImageResource(R.drawable.image placeholder); 
BitmapWorkerTask task - new BitmapWorkerTask(mImageView); 
task.execute(resId); 


// include BitmapWorkerTask class 


public class ImageDetailFragment extends Fragment { 


@Override 
public void onActivityCreated(Bundle savedInstanceState) { 
super.onActivityCreated(savedInstanceState); 
if (ImageDetailActivity.class.isInstance(getActivity())) { 
final int resId = ImageDetailActivity.imageResIds[mImageNum]; 
// Call out to ImageDetailActivity to load the bitmap in a background thre 
ad 
((ImageDetailActivity) getActivity()).loadBitmap(resId, mImageView); 


在 BitmapWorkerTask 中 做 一 些 例如 重 设 图 片 大 小 ， 从 网 络 拉 取 图 片 的 任务 ， 可 以 确保 不 会 阻 
塞 UI 线程 。 如 果 后 台 线 程 不 仅仅 是 一 个 简单 的 加 载 操作 ， 增 加 一 个 内 存 缓 存 或 者 磁盘 缓存 会 
比较 好 (请 参考 第 三 课 : 缓存 Bitmap ) ， 下 面 是 一 些 为 了 内 存 缓存 而 附加 的 内 容 : 


public class ImageDetailActivity extends FragmentActivity { 
private LruCache mMemoryCache; 


@Override 
public void onCreate(Bundle savedInstanceState) { 


// initialize LruCache as per Use a Memory Cache section 


public void loadBitmap(int resId, ImageView imageView) { 
final String imageKey - String.valueOf(resId); 


final Bitmap bitmap - mMemoryCache.get(imageKey); 

if (bitmap != null) { 
mImageView.setImageBitmap(bitmap); 

else { 
mImageView.setImageResource(R.drawable.image placeholder); 
BitmapWorkerTask task - new BitmapWorkerTask(mImageView); 
task.execute(resId); 


// include updated BitmapWorkerTask from Use a Memory Cache section 


把 前 面 学 习 到 的 所 有 技巧 合并 起 来 ， 我 们 将 得 到 一 个 响应 性 良好 的 ViewPager 实 现 : 它 拥有 最 
小 的 加 载 延 迟 ， 同 时 可 以 根据 实际 需求 执行 不 同 的 后 台 处 理 任务 。 


实现 加 载 图 片 到 GridView 


Grid List Building Block 是 一 种 有 效 显示 大 量 图 片 的 方式 。 它 能 够 一 次 显示 许多 图 片 ， 同 时 即 
将 被 显示 的 图 片 会 处 于 准备 显示 的 状态 。 如 果 我 们 想 要 实现 这 种 效果 ， 必 须 确保 Ul 是 流畅 
的 ， 能 够 控制 内 存 使 用 ， 并 且 正 确 处 理 并 发 问题 (因为 GridView 会 循环 使 用 子 视图 )。 


下 面 是 一 个 典型 的 使 用 场景 ， 在 Fragment 里 面 内 置 GridView， 其 中 GridView 的 子 视图 是 
ImageView : 


public class ImageGridFragment extends Fragment implements AdapterView.OnItemClickList 
ener 1 
private ImageAdapter mAdapter; 


// A static dataset to back the GridView adapter 
public final static Integer[] imageResIds = new Integer[] { 
R.drawable.sample image 1, R.drawable.sample image 2, R.drawable.sample im 
age 3, 
R.drawable.sample image 4, R.drawable.sample image 5, R.drawable.sample im 


age 6, 


R.drawable.sample image 7, R.drawable.sample image 8, R.drawable.sample im 


age 9j; 


); 


// Empty constructor as per Fragment docs 
public ImageGridFragment() {} 


@Override 

public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
mAdapter - new ImageAdapter(getActivity()); 


QOverride 
public View onCreateView( 
LayoutInflater inflater, ViewGroup container, 


Bundle savedInstanceState) { 


final View v - inflater.inflate(R.layout.image grid fragment, container, false 


final GridView mGridView - (GridView) v.findViewById(R.id.gridView); 


mGridView.setAdapter(mAdapter); 
mGridView.setOnItemClickListener(this); 
return v; 


@Override 


public void onItemClick(AdapterView parent, View v, int position, long id) { 


final Intent i = new Intent(getActivity(), ImageDetailActivity.class); 
i.putExtra(ImageDetailActivity.EXTRA IMAGE, position); 


startActivity(i); 


private class ImageAdapter extends BaseAdapter { 
private final Context mContext; 


public ImageAdapter(Context context) { 
super(); 
mContext - context; 


@Override 
public int getCount() { 
return imageResIds. length; 


@Override 
public Object getItem(int position) { 
return imageResIds[position]; 


@Override 
public long getItemId(int position) { 
return position; 


@Override 


public View getView(int position, View convertView, ViewGroup container) { 
ImageView imageView; 


if (convertView -- null) ( // if it's not recycled, initialize some attrib 
utes 
imageView - new ImageView(mContext); 
imageView.setScaleType(ImageView.ScaleType.CENTER CROP); 
imageView.setLayoutParams(new GridView.LayoutParams( 
LayoutParams.MATCH PARENT, LayoutParams.MATCH PARENT)); 
} else { 
imageView = (ImageView) convertView; 
j 
// 请 注意 下 面 的 代码 
imageView. setImageResource(imageResIds[position]); // Load image into ImageView 
return imageView; 
} 
} 


4 — 


这 里 同样 有 一 个 问题 ， 上 面 的 代码 实现 中 ， 犯 了 把 图 片 加 载 放 在 UI 线程 进行 处 理 的 错误 。 如 
果 只 是 加 载 一 些 很 小 的 图 片 ， 或 者 是 经 过 Android 系 统 缩 放 并 缓存 过 的 图 片 ， 上 面 的 代码 在 运 
行 时 不 会 有 太 大 问题 ， 但 是 如 果 加 载 的 图 片 稍微 复杂 耗 时 一 点 ， 这 都 会 导致 你 的 UI 卡 顿 甚 至 
应 用 无 响应 。 


与 前 面 加 载 图 片 到 ViewPager 一 样 ， 如 果 setImageResource 的 操作 会 比较 耗 时 ， 也 有 可 能 会 阻 
塞 UI 线 程 。 不 过 我 们 可 以 使 用 类 似 前 面 异 步 处 理 图 片 与 增加 缓存 的 方法 来 解决 这 个 问题 。 然 
而 ， 我 们 还 需要 考虑 GridView 的 循环 机 制 所 带 来 的 并 发 问题 。 为 了 处 理 这 个 问题 ， 可 以 参考 
前 面 的 课程 。 下 面 是 一 个 更 新 过 后 的 解决 方案 : 


public class ImageGridFragment extends Fragment implements AdapterView.OnItemClickList 
ener 1 


private class ImageAdapter extends BaseAdapter { 


@Override 


public View getView(int position, View convertView, ViewGroup container) { 


loadBitmap(imageResIds[position], imageView) 
return imageView; 


public void loadBitmap(int resId, ImageView imageView) { 
if (cancelPotentialWork(resId, imageView)) { 
final BitmapWorkerTask task = new BitmapWorkerTask(imageView) ; 
final AsyncDrawable asyncDrawable = 


new AsyncDrawable(getResources(), mPlaceHolderBitmap, task); 
imageView.setImageDrawable(asyncDrawable) ; 
task.execute(resId); 


static class AsyncDrawable extends BitmapDrawable { 
private final WeakReference bitmapWorkerTaskReference; 


public AsyncDrawable(Resources res, Bitmap bitmap, 
BitmapworkerTask bitmapWorkerTask) { 
super(res, bitmap); 
bitmapworkerTaskReference = 
new WeakReference(bitmapWorkerTask); 


public BitmapWorkerTask getBitmapWorkerTask() { 
return bitmapWorkerTaskReference.get(); 


public static boolean cancelPotentialWork(int data, ImageView imageView) { 
final BitmapWorkerTask bitmapWorkerTask - getBitmapWorkerTask(imageView); 


if (bitmapWorkerTask !- null) { 

final int bitmapData = bitmapWorkerTask.data; 

if (bitmapData != data) { 
// Cancel previous task 
bitmapWorkerTask.cancel(true); 

} else { 
// The same work is already in progress 
return false; 


} 


// No task associated with the ImageView, or an existing task was cancelled 
neturm true, 


private static BitmapWorkerTask getBitmapWorkerTask(ImageView imageView) { 
if (imageView != null) { 
final Drawable drawable - imageView.getDrawable(); 
if (drawable instanceof AsyncDrawable) { 
final AsyncDrawable asyncDrawable = (AsyncDrawable) drawable; 
return asyncDrawable.getBitmapWorkerTask(); 


} 


return null; 


. // include updated BitmapWorkerTask class 


Note: 对 于 ListView 同 样 可 以 套用 上 面 的 方法 。 


上 面 的 方法 提供 了 足够 的 弹性 ， 使 得 我 们 可 以 做 从 网 络 下载 图 片 ， 并 对 大 尺寸 大 的 数码 照片 
做 缩放 等 操作 而 不 至 于 阻塞 UI 线 程 。 


使 用 OpenGL ES 显示 图 像 


编写 :jdneo - 原文 :http://developer.android.com/training/graphics/opengl/index.html 


Android framework 提供 了 大 量 的 标准 视图 工具 ， 用 poesi ' 功能 丰富 的 图 形 界 面 。 
然而 ， 如 果 我 们 希望 应 用 能 够 对 屏幕 上 所 绘制 的 内 容 进行 更 多 的 控制 ， 或 者 是 硕 望 绘制 3D 图 
像 ， 那 么 我 们 就 需要 一 个 不 同 的 工具 了 。 由 Android framework 的 OpenGL ES 接口 给 予 
我 们 一 组 可 以 ET 的 工具 集 ， 它 能 够 完成 超越 我 们 想象 力 的 复杂 多 变 的 图 形 

绘制 。 同 时 ， 这 些 绘制 操作 在 绝 大 多 数 的 Android 设备 上 ， 都 能 够 利用 设备 自身 装载 的 图 形 
处 理 单元 (GPU ) 为 其 提供 更 好 的 性 能 。 


这 系列 课程 将 展示 如 何 使 用 OpenGL 构建 应 用 的 基础 知识 ， 和 包括 配置 启动 ， 绘 制 对 象 ， 移 动 
图 形 元 素 以 及 响应 点 击 事件 。 


这 系列 课程 所 涉及 的 样 例 代码 使 用 的 是 OpenGL ES 2.0 接口 ， 这 是 当前 Android 设 备 所 推荐 
的 接口 版 本 。 关 于 更 多 OpenGL ES 的 版 本 信息 ， 可 以 阅读 : OpenGL 开 发 手册 。 


Note : 注意 不 要 把 OpenGL ES 1.x 版 本 的 接口 和 OpenGL ES 2.0 的 接口 混合 调用 。 这 两 
种 版 本 的 接口 不 是 通用 的 。 如 果 党 试 混用 它们 可 能 会 让 你 感到 无 奈 和 泪 丧 。 


Sample Code 


OpenGLES.zip 


Lessons 


e 配置 OQpenGL ES 的 环境 (Building an OpenGL ES Environment) 
学 习 如 何 配置 一 个 可 以 绘制 OpenGL. 图 形 的 Android 应 用 。 
e 定义 形状 (Defining Shapes) 


学 习 如 何 定 义 形状 ， 以 及 为 何 需 要 了 解 面 (Faces) 和 卷 绕 (Winding) 这 两 个 概念 的 原 
à 


e 绘制 形状 (Drawing Shapes) 
学 习 如 何在 应 用 中 利用 OpenGL 绘 制 形状 。 
e 运用 投影 与 相机 视角 (Applying Projection and Camera Views) 


学 习 如 何 通过 投影 和 相机 视角 ， 获 取 图 形 对 象 的 一 个 新 的 透视 效果 。 


使 用 DpenGL ES 显示 图 像 


e 添加 移动 (Adding Motion) 
学 习 如 何 对 一 个 OpenGL 图 形 对 象 添加 基本 的 运动 效果 。 


e 响应 触摸 事件 (Responding to Touch Events) 


学 习 如 何 与 OpenGL 图 形 进行 基本 的 交互 。 
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建立 OpenGL ES 的 环境 (Building an 
OpenGL ES Environment) 


编写 :jdneo - 原 
x-:http;//developer.android.com/training/graphics/opengl/environment.html 


要 在 应 用 中 使 用 OpenGL ES 绘制 图 像 ， 我 们 必须 为 它们 创建 一 个 View 容器 。 一 种 比较 直接 
的 方法 是 实现 GLSurfaceView 类 和 GLSurfaceView.Renderer 类 。 其 中 ，GLSurfaceView X 
一 个 View 容 器 ， 它 用 来 存放 使 用 OpenGL 绘制 的 图 形 ， 而 GLSurfaceView.Renderer 则 用 来 
控制 在 该 View 中 绘制 的 内 容 。 关 于 这 两 个 类 的 更 多 信息 ， 你 可 以 阅读 : OpenGL ES 开发 手 
册 。 


使 用 GLSurfaceView 只 是 一 种 将 OpenGL ES 集成 到 应 用 中 的 方法 之 一 。 对 于 一 个 全 屏 的 或 
者 接近 全 屏 的 图 形 View， 使 用 它 是 一 个 合理 的 选择 。 开 发 者 如 果 希 望 把 OpenGL ES 的 图 形 

集成 到 整个 布局 的 一 小 部 分 里 面 ， 那 么 可 以 考虑 使 用 TextureView。 对 于 喜欢 自己 动手 实现 的 
开发 者 来 说 ， 还 可 以 通过 使 用 SurfaceView 搭建 一 个 OpenGL ES 的 视图 环境 ， 但 是 这 将 会 

需要 我 们 编写 更 多 额外 的 代码 。 


在 这 节 课 中 ， 我 们 将 展示 如 何在 一 个 简单 的 Activity 程序 中 完成 GLSurfaceView 和 
GLSurfaceView.Renderer 的 完整 落地 实现 。 


在 Manifest 配置 文件 中 声明 使 用 OpenGL ES 
(Declare OpenGL ES Use in the Manifest) 


为 了 让 应 用 能 够 使 用 OpenGL ES 2.0 接口 ， 我 们 必须 将 下 列 声明 添加 到 Manifest 配置 文件 当 
中 : 


«uses-feature android:glEsVersion-"0x00020000" android:required-"true" /> 


mc 的 应 用 使 用 纹理 压缩 (Texture Compression) ， 那 么 我 们 必须 对 支持 的 压缩 格式 也 
进行 声明 ， 确 保 应 用 仅 安 装 在 可 以 兼容 的 设备 上 : 


«supports-gl-texture android:name-"GL OES compressed ETC1 RGB8 texture" /> 
«supports-gl-texture android:name-"GL OES compressed paletted texture" /» 


更 多 关于 纹理 压缩 的 内 容 ， 可 以 阅读 : OpenGL 开 发 手册 。 


为 OpenGL ES 图 形 创建 Activity (Create an 
Activity for OpenGL ES Graphics) 


Android 应 用 在 呈现 OpenGL ES 的 时 候 会 使 用 activity 作为 用 户 界面 ， 这 和 其 他 应 用 也 同样 
会 使 用 一 个 用 户 界面 进行 呈现 交互 的 道理 一 样 。 主 要 的 差别 就 是 往 acitivity 布局 内 容 上 的 的 输 
入 差异 。 在 其 他 应 用 中 你 可 能 会 使 用 TextView，Button 和 ListView 等 等 ， 而 在 使 用 OpenGL 
ES 的 应 用 中 ， 我 们 还 可 以 添加 一 个 GLSurfaceView ° 


下 面 的 代码 展示 了 一 个 使 用 GLSurfaceView 作为 其 主 View 的 Activity : 


public class OpenGLES20Activity extends Activity { 
private GLSurfaceView mGLView; 


@Override 
public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


// Create a GLSurfaceView instance and set it 
// as the ContentView for this Activity. 
mGLView = new MyGLSurfaceView(this); 
setContentView(mGLView); 


u 


Note : OpenGL ES 2.0 € € Android 2.2 (API Level 8) 或 更 高 版 本 的 系统 ， 所 以 确保 
你 的 Android 项 目的 API 版 本 满足 该 要 求 。 


构建 一 个 GLSurfaceView 对 象 (Build a 
GLSurfaceView Object) 


GLSurfaceView 是 一 种 比较 特殊 的 View， 我 们 可 以 在 该 View 中 绘制 OpenGL ES 图 形 ， 不 
过 它 自己 并 不 做 太 多 和 绘制 图 形 相 关 的 任务 。 绘 制 对 象 的 任务 是 由 你 在 该 View 中 配置 的 
GLSurfaceView.Renderer 所 控制 完成 的 。 事 实 上 ， 这 个 对 象 的 代码 非常 简短 ， 你 可 能 不 会 希 
望 继 承 它 ， 直 接 创建 一 个 未 经 修改 的 GLSurfaceView 实例 ， 不 过 请 不 要 这 么 做 ， 因 为 我 们 需 
要 继承 该 类 来 捕捉 触 控 事 件 ， 这 方面 知识 会 在 响应 触摸 事件 (该 系列 课程 的 最 后 一 节 课 ) 中 
做 进一步 的 介绍 。 


GLSurfaceView 的 核心 代码 非常 简短 ， 如 果 想 要 快速 的 实现 效果 ， 我 们 通常 可 以 在 Acitvity 中 
创建 一 个 内 部 类 并 使 用 它 : 


class MyGLSurfaceView extends GLSurfaceView { 
private final MyGLRenderer mRenderer; 


public MyGLSurfaceView(Context context)[( 
super(context); 


// Create an OpenGL ES 2.0 context 
setEGLContextClientVersion(2); 


mRenderer - new MyGLRenderer(); 


// Set the Renderer for drawing on the GLSurfaceView 
setRenderer (mRenderer); 


另 一 个 对 于 GLSurfaceView 实现 的 可 选项 ， 是 将 泻 染 模式 设置 
为 : GLSurfaceView.RENDERMODE WHEN_DIRTY， 其 含义 是 : 仅 在 你 的 绘制 数据 发 生变 
化 时 才 对 视图 进行 绘制 操作 : 


// Render the view only when there is a change in the drawing data 
setRenderMode(GLSurfaceView.RENDERMODE WHEN DIRTY); 


如 果 选 用 这 一 配置 选项 ， 那 么 除非 调用 了 requestRender() ， 否 则 GLSurfaceView 不 会 被 重 
新 绘制 ， 这 样 做 可 以 让 示例 中 的 应 用 效率 更 高 。 


构建 一 个 泻 业 类 (Build a Renderer Class) 


在 一 个 使 用 OpenGL ES 的 应 用 中 ， 一 个 GLSurfaceView.Renderer 类 的 实现 (或 者 我 们 将 其 
TRUE) ， 正 是 事情 变 得 有 趣 的 地 方 。 该 类 会 控制 和 其 相关 联 的 GLSurfaceView， 具 
体 而 言 ， 它 会 控制 在 GLSurfaceView 上 绘制 的 内 容 。 在 泻 染 器 中 ， 一 共有 三 个 方法 会 被 
Android 系 统 调用 ， 以 此 来 明确 要 在 GLSurfaceView 上 绘制 的 内 容 以 及 如 何 绘制 : 


e onSurfaceCreated() : 调用 一 次 ， 用 来 建立 View 的 OpenGL ES 环境 。 

e onDrawFrame() : 每 次 重新 绘制 View 时 被 调用 。 

e onSurfaceChanged() : 如 果 View 的 几何 形态 发 生变 化 时 会 被 调用 ， 例 如 当 设 备 的 屏幕 
方向 发 生 改 变 时 。 


下 面 是 一 个 非常 基本 的 OpenGL ES 浑 业 器 的 实现 ， 它 仅仅 在 GLSurfaceView 中 画 一 个 黑色 
的 背景 : 


public class MyGLRenderer implements GLSurfaceView.Renderer { 


public void onSurfaceCreated(GL10 unused, EGLConfig config) { 
// Set the background frame color 
GLES20.glClearColor(0.0f, 0.0f, 0.0f, 1.0f); 

} 


public void onDrawFrame(GL10 unused) { 
// Redraw background color 
GLES20.glClear(GLES20.GL COLOR BUFFER BIT); 





} 


public void onSurfaceChanged(GL10 unused, int width, int height) { 
GLES20.glViewport(0, 0, width, height); 
} 


就 是 这 样 | 上 面 的 代码 创建 了 一 个 简单 地 应 用 程序 ， dd OpenGL 让 屏幕 呈现 为 黑色 。 虽 
然 它 的 代码 看 上 去 并 没有 做 什么 非常 有 意思 的 事情 ， 但 是 通过 创建 这 些 类 ， 我 们 已 经 对 使 用 
OpenGL 绘制 图 形 有 了 基本 的 认识 和 铺垫 。 


Note : 你 可 能 想 知 道 ， 自 己 明明 使 用 的 是 bids ES 2.0 接口 ， 为 什么 这 些 方法 会 有 一 
个 GL10 的 参数 。 这 是 因为 这 些 方法 的 签名 〈Method Signature) 在 2.0 接 口中 被 简单 地 
重用 了 ， 以 此 来 保持 Android 框 架 的 代码 尽量 简单 。 


如 果 你 对 OpenGL ES 接口 很 熟悉 ， 那 么 你 现在 就 可 以 在 你 的 应 用 中 构建 一 个 DpenGL ES 的 环 
境 并 绘制 图 形 了 。 当 然 ， 如 果 你 希望 获取 更 多 的 帮助 来 学 会 使 用 DpenGL， 那 么 请 继续 学 习 
下 一 节 课 程 获取 更 多 的 知识 。 


NO 
IS 


定义 形状 (Defining Shapes) 


编写 :jdneo - Æ X:http://developer.android.com/training/graphics/opengl/shapes.html 


在 一 个 OpenGL ES View 的 上 下 文 (Context) 中 定义 形状 ， 是 创建 你 的 杰作 所 需要 的 第 一 
步 。 在 了 解 关于 OpenGL ES 如 何 定义 图 形 对 象 的 基本 知识 之 前 ， 想 通过 OpenGL ES 直接 绘 
图 可 能 会 有 些 困难 。 


这 节 课 将 讲解 OpenGL ES 相对 于 Android 设备 屏幕 的 坐标 系 ， 定 义 形 状 和 形状 表面 的 基本 知 
识 ， 例 如 定义 一 个 三 角形 和 一 个 矩形 。 


定义 一 个 三 角形 (Define a Triangle) 


OpenGL ES 人 允许 我 们 使 用 三 维 空间 的 坐标 系 来 定义 绘画 对 象 。 所 以 在 我 们 能 画 三 角形 之 前 ， 
必须 先 定 义 它 的 坐标 。 在 OpenGL 中 ， 典 型 的 办 法 是 为 坐标 定义 一 个 浮 点 型 的 顶点 数组 。 为 
了 高 效 起 见 ， 我 们 可 以 将 坐标 写 入 一 个 ByteBuffer， 它 将 会 传 入 OpenGI ES 的 图 形 处 理 流程 
中 : 


public class Triangle { 
private FloatBuffer vertexBuffer; 
// number of coordinates per vertex in this array 


static final int COORDS PER VERTEX - 3; 
static float triangleCoords[] = { // in counterclockwise order: 


0.0f, ©.622008459f, 0.0f, // top 
-0.5f, -0.311004243f, 0.0f, // bottom left 
Q.5f, -0.311004243f, 0.0f // bottom right 


un 


// Set color with red, green, blue and alpha (opacity) values 
float color[] = { 0.63671875f, 0.76953125f, 0.22265625f, 1.0f }; 


public Triangle() { 
// initialize vertex byte buffer for shape coordinates 
ByteBuffer bb = ByteBuffer.allocateDirect( 
// (number of coordinate values * 4 bytes per float) 
triangleCoords.length * 4); 
// use the device hardware's native byte order 
bb.order(ByteOrder.nativeOrder()); 


// create a floating point buffer from the ByteBuffer 
vertexBuffer - bb.asFloatBuffer(); 

// add the coordinates to the FloatBuffer 
vertexBuffer.put(triangleCoords); 

// set the buffer to read the first coordinate 
vertexBuffer.position(9); 


默认 情况 下 ，OpenGL ES 会 假定 一 个 坐标 系 ， 在 这 个 坐标 系 中 ，[0, 0, 0] (分 别 对 应 X 轴 坐标 ， 
Y 轴 坐标 , Z 轴 坐标 ) 对 应 的 是 GLSurfaceView 的 中 心 。[1, 1, 0] 对 应 的 是 右上 角 ，[-1, -1, 0] 对 
应 的 则 是 左下 角 。 如 果 想 要 看 此 坐标 系 的 插图 说 明 ， 可 以 阅读 OpenGL ES 开发 手册 e 


注意 到 这 个 形状 的 坐标 是 以 北 时 针 顺 序 定 义 的 。 绘 制 的 顺序 非常 关键 ， 因 为 它 定 义 了 哪 一 面 
是 形状 的 正面 (希望 绘制 的 一 面 ) ， 以 及 背面 (使 用 OpenGL ES 的 Cull Face 功 能 可 以 让 背面 
不 要 绘制 ) 。 更 多 关于 该 方面 的 信息 ， 可 以 阅读 OpenGL ES 开发 手册 。 


定义 一 个 矩形 (Define a Square) 


在 OpenGL 中 定义 三 角形 非常 简单 ， 那 么 你 是 否 想 要 来 点 更 复杂 的 呢 ? 比如 ， 定 义 一 个 矩 
形 ? 有 很 多 方法 可 以 用 来 定义 矩形 ， 不 过 在 OpenGL ES 中 最 典型 的 办 法 是 使 用 两 个 三 角形 拼 
接 在 一 起 : 


定义 Shapes 


xl, yl, Z1 «———— — — x4，y4，z4 





x2, y2, z2— — — — — —fXx3, y3, z3 


再 一 次 地 ， 我 们 需要 逆 时 针 地 为 三 角形 顶点 定义 坐标 来 表现 这 个 图 形 ， 并 将 和 值 放 入 一 
个 ByteBuffer 中 。 为 了 避免 由 两 个 三 角形 重合 的 那 条 边 的 顶点 被 重复 定义 ， 可 以 使 用 一 个 绘制 
列表 来 告诉 OpenGL ES 图 形 处 理 流程 应 该 如 何 画 这 些 顶 点 。 下 面 是 代码 样 例 : 
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public class Square { 


private FloatBuffer vertexBuffer; 
private ShortBuffer drawListBuffer; 


// number of coordinates per vertex in this array 
static final int COORDS PER VERTEX - 3; 
static float squareCoords[] = { 
-@.5f,  0.5f, O.O0f, // top left 
-Q.bf, -0.5f, O.Of, // bottom left 
gubt “Onsf, 9.0. // bottom right 
oS Onon OLOR 7E bODISIEO Dit 


private short drawOrder[] = { 0, 1, 2, 0, 2, 3 }; // order to draw vertices 


public Square() { 

// initialize vertex byte buffer for shape coordinates 

ByteBuffer bb = ByteBuffer.allocateDirect( 

// (# of coordinate values * 4 bytes per float) 
squareCoords.length * 4); 

bb.order(ByteOrder.nativeOrder()); 

vertexBuffer - bb.asFloatBuffer(); 

vertexBuffer.put(squareCoords); 

vertexBuffer.position(9); 


// initialize byte buffer for the draw list 
ByteBuffer dlb - ByteBuffer.allocateDirect( 
// (# of coordinate values * 2 bytes per short) 
drawOrder.length * 2); 
dlb.order(ByteOrder.nativeOrder()); 
drawListBuffer - dlb.asShortBuffer(); 
drawListBuffer.put(drawOrder); 
drawListBuffer.position(0); 


该 样 例 可 以 看 作 是 一 个 如 何 使 用 OpenGL 创建 复杂 图 形 的 启发 ， 通 常 来 说 ， 我 们 需要 使 用 三 
角形 的 集合 来 绘制 对 象 。 在 下 一 节 课 中 ， 我 们 将 学 习 如 何在 屏幕 上 画 这 些 形 状 。 


绘制 形状 (Drawing Shapes) 


编写 :jdneo - /$ xc:http://developer.android.com/training/graphics/opengl/draw.html 


在 定义 了 将 要 绘制 的 形状 之 后 ， 你 可 能 希望 使 用 OpenGL 绘制 出 它们 。 使 用 OpenGL ES 2.0 
绘制 图 形 可 能 会 比 你 想象 当中 更 复杂 一 些 ， 因 为 API 中 提供 了 大 量 对 于 图 形 泻 染 流程 的 控 
制 。 


这 节 课 将 解释 如 何 使 用 OpenGL ES 2.0 接口 画 出 在 上 一 节 课 中 定义 的 形状 。 


初始 化 形状 (Initialize Shapes) 


在 你 开始 绘画 之 前 ， 你 需要 初始 化 并 加 载 你 期 望 绘制 的 图 形 。 除 非 你 所 使 用 的 形状 结构 CR 
始 坐标 ) 在 执行 过 程 中 发 生 了 变化 ， 不 然 的 话 你 应 该 在 浑 染 器 的 onSurfaceCreated() 方法 中 
初始 化 它们 ， 这 样 做 是 出 于 内 存 和 执行 效率 的 考量 。 


public class MyGLRenderer implements GLSurfaceView.Renderer { 


private Triangle mTriangle; 
private Square mSquare; 


public void onSurfaceCreated(GL10 unused, EGLConfig config) { 


// initialize a triangle 
mTriangle - new Triangle(); 
// initialize a square 


mSquare = new Square(); 


画 一 个 形状 (Draw a Shape) 


使 用 OpenGL ES 2.0 画 一 个 定义 好 的 形状 需要 较 多 代码 ， 因 为 你 需要 提供 很 多 图 形 演 染 流程 
的 细节 。 具 体 而 言 ， 你 必须 定义 如 下 几 项 : 


e 顶点 着 色 器 (Vertex Shader) : 用 来 泻 染 形状 顶点 的 OpenGL ES 代码 。 
。 片段 着 色 器 (Fragment Shader) : 使 用 颜色 或 纹理 泻 染 形 状 表 面 的 OpenGL ES 代码 。 
e 程式 (Program) :一 个 OpenGL ES 对 象 ， 包 含 了 你 希望 用 来 绘制 一 个 或 更 多 图 形 所 要 


用 到 的 着 色 器 。 


你 需要 至 少 一 个 顶点 着 色 器 来 绘制 一 个 形状 ， 以 及 一 个 片段 着 色 器 为 该 形状 上 色 。 这 些 着 色 
器 必须 被 编译 然后 添加 到 一 个 OpenGL ES Program 当中 ， 并 利用 它 来 绘制 形状 。 下 面 的 代 
码 在 Triangle 类 中 定义 了 基本 的 着 色 器 ， 我 们 可 以 利用 它们 绘制 出 一 个 图 形 : 


public class Triangle { 


private final String vertexShaderCode - 
"attribute vec4 vPosition;" + 
"void main() {" + 
" gl Position = vPosition;" + 


Mts 


private final String fragmentShaderCode - 
"precision mediump float;" + 
"uniform vec4 vColor;" + 
"void main() {" + 
" gl FragColor = vColor;" + 


Mn . 
下 


着 色 器 包含 了 OpenGL Shading Language (GLSL) 代码 ， 它 必须 先 被 编译 然后 才能 在 
OpenGL 环境 中 使 用 。 要 编译 这 些 代 码 ， 需 要 在 你 的 泻 染 器 类 中 创建 一 个 辅助 方法 : 


public static int loadShader(int type, String shaderCode) { 


// create a vertex shader type (GLES20.GL VERTEX SHADER) 
// or a fragment shader type (GLES20.GL FRAGMENT SHADER) 
int shader = GLES20.glCreateShader(type); 


// add the source code to the shader and compile it 
GLES20.glShaderSource(shader, shaderCode); 
GLES20.glCompileShader(shader); 


return shader; 


为 了 绘制 你 的 图 形 ， 你 必须 编译 着 色 器 代码 ， 将 它们 添加 至 一 个 opener ES Program 对 象 
中 ， 然 后 执行 链接 。 在 你 的 绘制 对 象 的 构造 函数 里 做 这 些 事情 ， 这 样 上 述 步 又 就 只 用 执行 一 


Note : 编译 OpenGL ES 着 色 器 及 链接 操作 对 于 CPU 周期 和 处 理 时 间 而 言 ， 消 耗 是 巨大 
的 ， 所 以 你 应 该 避免 重复 执行 这 些 事情 。 如 果 在 执行 期 间 不 知道 着 色 器 的 内 容 ， 那 么 你 
应 该 在 构建 你 的 应 用 时 ， 确 保 它 们 只 被 创建 了 一 次 ， 并 且 缓 存 以 备 后 续 使 用 。 


public class Triangle() { 


private final int mProgram; 


public Triangle() { 


int vertexShader - MyGLRenderer.loadShader(GLES20.GL VERTEX SHADER, 
vertexShaderCode); 

int fragmentShader - MyGLRenderer.loadShader(GLES20.GL FRAGMENT SHADER, 
fragmentShaderCode); 


// create empty OpenGL ES Program 
mProgram = GLES20.glCreateProgram(); 


// add the vertex shader to program 
GLES20.glAttachShader(mProgram, vertexShader); 


// add the fragment shader to program 
GLES20.glAttachShader(mProgram, fragmentShader); 


// creates OpenGL ES program executables 
GLES20.glLinkProgram(mProgram); 


至 此 ， 你 已 经 完全 准备 好 添加 实际 的 调用 语句 来 绘制 你 的 图 形 了 。 使 用 OpenGL ES 绘制 图 形 
需要 你 定义 一 些 变量 来 告诉 润 染 流程 你 需要 绘制 的 内 容 以 及 如 何 绘制 。 既 然 绘制 属性 会 根据 
形状 的 不 同 而 发 生变 化 ， 把 绘制 逻 辑 包 含 在 形状 类 里 面 将 是 一 个 不 错 的 主意 。 


创建 一 个 draw() 方法 来 绘制 图 形 。 下 面 的 代码 为 形状 的 顶点 着 色 器 和 形状 着 色 器 设置 了 位 置 
和 颜色 值 ， 然 后 执行 绘制 函数 : 


private int mPositionHandle; 
private int mColorHandle; 


private final int vertexCount - triangleCoords.length / COORDS PER VERTEX; 
private final int vertexStride - COORDS PER VERTEX * 4; // 4 bytes per vertex 


public void draw() { 
// Add program to OpenGL ES environment 
GLES20.glUseProgram(mProgram); 


// get handle to vertex shader's vPosition member 
mPositionHandle - GLES20.glGetAttribLocation(mProgram, "vPosition"); 


// Enable a handle to the triangle vertices 
GLES20.glEnableVertexAttribArray(mPositionHandle); 


// Prepare the triangle coordinate data 

GLES20.glVertexAttribPointer(mPositionHandle, COORDS PER VERTEX, 
GLES20.GL FLOAT, false, 
vertexStride, vertexBuffer); 


// get handle to fragment shader's vColor member 
mColorHandle - GLES20.glGetUniformLocation(mProgram, "vColor"); 


// Set color for drawing the triangle 
GLES20.glUniform4fv(mColorHandle, i, color, 0); 


// Draw the triangle 
GLES20.glDrawArrays(GLES20.GL TRIANGLES, 0, vertexCount); 


// Disable vertex array 
GLES20.glDisableVertexAttribArray(mPositionHandle); 


joy 


一 旦 你 完成 了 上 述 所 有 代码 ， 仅 需要 在 你 演 染 器 的 onDrawFrame() 方 法 中 调用 draw() 方法 就 
可 以 画 出 我 们 想 要 画 的 对 象 了 : 


public void onDrawFrame(GL10 unused) { 


mTriangle.draw(); 


当 你 运行 这 个 应 用 时 ， 它 看 上 去 会 像 是 这 样 : 
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在 这 个 代码 样 例 中 ， 还 存在 一 些 问题 。 首 先 ， 它 无 法 给 用 户 带 来 什么 深刻 的 印象 。 其 次 ， 这 
个 三 角形 看 上 去 有 一 些 扁 ， 另 外 当 你 改变 屏幕 方向 时 ， 它 的 形状 也 会 随 之 改变 。 发 生 形 变 的 
原因 是 因为 对 象 的 顶点 没有 根据 显示 GLSurfaceView 的 屏幕 区 域 的 长 宽 比 进行 修正 。 你 可 以 在 
下 一 节 课 中 使 用 投影 (Projection) 或 者 相机 视角 (Camera View) 来 解决 这 个 问题 。 


最 后 ， 这 个 三 角形 是 静止 的 ， 这 看 上 去 有 些 无 聊 。 在 添加 移动 课程 当中 《后续 课程 ) ， 你 会 
让 这 个 形状 发 生 旋转 ， 并 使 用 一 些 OpenGL ES 图 形 处 理 流 程 中 更 加 新 奇 的 用 法 。 


运用 投影 与 相机 视角 


编写 :jdneo - 原文 :http://developer.android.com/training/graphics/opengl/projection.html 


在 OpenGL ES 环境 中 ， 利 用 投影 和 相机 视角 可 以 让 显示 的 绘图 对 象 更 加 酷似 于 我 们 用 肉眼 看 
到 的 真实 物体 。 该 物理 视角 的 仿 站 是 对 绘制 对 象 坐 标的 进行 数学 变换 实现 的 : 


。 122% (Projection) : 这 个 变换 会 基于 显示 它们 的 GLSurfaceView 的 长 和 宽 ， 来 调整 绘 
对 象 的 坐标 。 如 果 没 有 该 计算 ， 那 么 用 OpenGL ES 绘制 的 对 象 会 由 于 其 长 宽 比 例 和 View 
窗口 比例 的 不 一 致 而 发 生 形变 。 一 个 投影 变换 一 般 仅 当 OpenGL View 的 比例 在 泻 染 器 的 
onSurfaceChanged() 方 法 中 建立 或 发 生变 化 时 才 被 计算 。 关 于 更 多 OpenGL ES 投影 和 坐 
标 映射 的 知识 ， 可 以 阅读 Mapping Coordinates for Drawn Objects ° 

e 相机 视角 (Camera View) : 这 个 变换 会 基于 一 个 虚拟 相机 位 置 改 变 绘图 对 象 的 坐标 。 
注意 到 OpenGL ES 并 没有 定义 一 个 实际 的 相机 对 象 ， 取 而 代 之 的 ， 它 提供 了 一 些 辅助 方 
法 ， 通 过 对 绘图 对 象 的 变换 来 模拟 相机 视角 。 一 个 相机 视角 变换 可 能 仅 在 建立 你 的 
GLSurfaceView 时 计算 一 次 ， 也 可 能 根据 用 户 的 行为 或 者 你 的 应 用 的 功能 进行 动态 调整 。 


这 节 课 将 解释 如 何 创 建 一 个 投影 和 一 个 相机 视角 ， 并 应 用 它们 到 GLSurfaceView 中 的 绘制 图 像 
上 o 


` 


定义 一 个 投影 


投影 变换 的 数据 会 在 GLSurfaceView.Renderer 类 的 onSurfaceChanged() 方 法 中 被 计算 。 下 面 
的 代码 首先 接收 GLSurfaceView 的 高 和 宽 ， 然 后 利用 它 并 使 用 Matrix.frustumM() 方 法 来 填充 一 
个 投影 变换 和 矩阵 (Projection Transformation Matrix ) 


// mMVPMatrix is an abbreviation for "Model View Projection Matrix" 
private final float[] mMVPMatrix = new float[16]; 

private final float[] mProjectionMatrix - new float[16]; 

private final float[] mViewMatrix - new float[16]; 


@Override 
public void onSurfaceChanged(GL10 unused, int width, int height) { 
GLES20.glViewport(0, ©, width, height); 


float ratio - (float) width / height; 
// this projection matrix is applied to object coordinates 


// in the onDrawFrame() method 
Matrix.frustumM(mProjectionMatrix, 0, -ratio, ratio, -1, 1, 3, 7); 


该 代码 填充 了 一 个 投影 矩阵 : mProjectionMatrix， 在 下 一 节 中 ， 我 们 可 以 在 onDrawFrame() 
方法 中 将 它 和 一 个 相机 视角 变换 结合 起 来 。 


Note : 在 绘图 对 象 上 只 应 用 一 个 投影 变换 会 导致 显示 效果 看 上 去 很 空旷 。 一 般 而 言 ， 我 
们 还 要 实现 一 个 相机 视角 ， 使 得 所 有 对 象 出 现在 屏幕 上 。 


定义 一 个 相机 视角 


在 泻 染 器 中 添加 一 个 相机 视角 变换 作为 绘图 过 程 的 一 部 分 ， 以 此 完成 我 们 的 绘图 对 象 所 需 变 
换 的 所 有 步 又。 在 下 面 的 代码 中 ， 使 用 Matrix.setLookAtM() 方 法 来 计算 相机 视角 变换 ， 然 后 
与 之 前 计算 的 投影 矩阵 结合 起 来 ， 结 合 后 的 变换 矩阵 传递 给 绘制 图 像 : 


@Override 
public void onDrawFrame(GL10 unused) { 


// Set the camera position (View matrix) 
Matrix.setLookAtM(mViewMatrix, ©, 0, ©, -3, Of, Of, Of, Of, 1.0f, 0.0f); 


// Calculate the projection and view transformation 
Matrix.multiplyMM(mMVPMatrix, 0, mProjectionMatrix, 0, mViewMatrix, 9); 


// Draw shape 
mTriangle.draw(mMVPMatrix); 


应 用 投影 和 相机 变换 


为 了 使 用 在 之 前 章节 中 结合 了 的 相机 视角 变换 和 投影 变换 ， 我 们 首先 为 之 前 在 Triangle 类 中 定 
义 的 顶点 着 色 器 添加 一 个 Matrix 变 量 : 





public class Triangle { 


private final String vertexShaderCode - 
// This matrix member variable provides a hook to manipulate 
// the coordinates of the objects that use this vertex shader 
"uniform mat4 uMVPMatrix;" + 
"attribute vec4 vPosition;" + 
"void main() {" + 
// the matrix must be included as a modifier of gl Position 
// Note that the uMVPMatrix factor *must be first* in order 
// for the matrix multiplication product to be correct. 
" gl Position = uMVPMatrix * vPosition;" + 


"wu . 
, 


// Use to access and set the view transformation 
private int mMVPMatrixHandle; 


之 后 ， 修 改 图 形 对 象 的 draw() 方法 ， 使 得 它 接收 组 合 后 的 变换 矩阵 ， 并 将 它 应 用 到 图 形 上 : 


public void draw(float[] mvpMatrix) { // pass in the calculated transformation matrix 
// get handle to shape's transformation matrix 
mMVPMatrixHandle - GLES20.glGetUniformLocation(mProgram, "uMVPMatrix"); 


// Pass the projection and view transformation to the shader 
GLES20.glUniformMatrix4fv(mMVPMatrixHandle, 1, false, mvpMatrix, 0); 


// Draw the triangle 
GLES20.glDrawArrays(GLES20.GL TRIANGLES, 0, vertexCount); 


// Disable vertex array 
GLES20.g1DisableVertexAttribArray(mPositionHandle) ; 


一 旦 我 们 正确 地 计算 并 应 用 了 投影 变换 和 相机 视角 变换 ， 我 们 的 图 形 就 会 以 正确 的 比例 绘制 
出 来 ， 它 看 上 去 会 像 是 这 样 : 
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现在 ， 应 用 已 经 可 以 通过 正确 的 比例 显示 图 形 了 ， 下 面 就 为 图 形 添 加 一 些 动画 效果 吧 ! 


添加 移动 


编写 :jdneo - 原文 :http://developer.android.com/training/graphics/opengl/motion.html 


在 屏幕 上 绘制 图 形 是 OpenGL 的 一 个 基本 特性 ， 当 然 我 们 也 可 以 通过 其 它 的 Android 图 形 框架 
类 做 这 些 事情 ， 包括 Canvas 和 Drawable 对 象 。OpenGL ES 的 特别 之 处 在 于 ， 它 还 提供 了 其 
它 的 一 些 功能 ， 比 如 在 三 维 空间 中 对 绘制 图 形 进行 移动 和 变换 操作 ， 或 者 通过 其 它 独 有 的 方 
法 创建 出 引人入胜 的 用 户 体验 。 


在 这 节 课 中 ， 我 们 会 更 深入 地 学 习 OpenGL ES 的 知识 : 对 一 个 图 形 添 加 旋转 动画 。 


旋转 一 个 形状 


使 用 OpenGL ES 2.0 旋转 一 个 绘制 图 形 是 比较 简单 的 。 在 泻 染 器 中 ， 创 建 另 一 个 变换 矩阵 
(一 个 旋转 矩阵 ) ， 并 且 将 它 和 我 们 的 投影 变换 矩阵 以 及 相机 视角 变换 矩阵 结合 在 一 起 : 


private float[] mRotationMatrix = new float[16]; 
public void onDrawFrame(GL10 gl) { 
float[] scratch - new float[16]; 


// Create a rotation transformation for the triangle 

long time = SystemClock.uptimeMillis() % 406001; 

float angle - 0.090f * ((int) time); 
Matrix.setRotateM(mRotationMatrix, 0, angle, 0, 0, -1.0f); 


// Combine the rotation matrix with the projection and camera view 
// Note that the mMVPMatrix factor *must be first* in order 

// for the matrix multiplication product to be correct. 
Matrix.multiplyMM(scratch, 0, mMVPMatrix, 0, mRotationMatrix, 9); 


// Draw triangle 
mTriangle.draw(scratch); 


如 果 完 成 了 这 些 变 更 以 后 ， 你 的 三 角形 还 是 没有 旋转 的 话 ， 确 认 一 下 你 是 否 将 启 
用 GLSurfaceView.RENDERMODE WHEN_DIRTY 的 这 一 配置 所 对 应 的 代码 注释 掉 了 ， 有 关 
该 方面 的 知识 会 在 下 一 节 中 展开 。 


如 果 严 格 按照 这 节 课 的 样 例 代码 走 到 了 现在 这 一 步 ， 那 么 请 确认 一 下 是 否 将 设置 泻 染 模 式 
为 RENDERMODE WHEN DIRTY 的 那 行 代码 注释 了 ， 不 然 的 话 OpenGL 只 会 对 这 个 形状 执行 一 次 旋 
转 ， 然 后 就 等 待 GLSurfaceView 容 器 的 requestRender()) 方 法 被 调用 后 才 会 继续 执行 泻 染 操 
作 。 


public MyGLSurfaceView(Context context) { 


// Render the view only when there is a change in the drawing data. 
// To allow the triangle to rotate automatically, this line is commented out: 
//setRenderMode(GLSurfaceView.RENDERMODE WHEN. DIRTY); 


除非 某 个 对 象 ， 它 的 变化 和 用 户 的 交互 无 关 ， 不 然 的 话 一 般 还 是 建议 将 这 个 配置 打开 。 在 下 
一 节 课 中 的 内 容 将 会 把 这 个 注释 放 开 ， 再 次 设 定 这 一 配置 选项 。 


响应 触摸 事件 


编写 :jdneo - 原文 :http://developer.android.com/training/graphics/opengl/touch.html 


让 对 象 根据 预 设 的 程序 运动 (如 让 一 个 三 角形 旋转 ) ， 可 以 有 效 地 引起 用 户 的 注意 ， 但 是 如 
果 和 希望 让 OpenGL ES 的 图 形 对 象 与 用 户 交 互 呢 ? 让 我 们 的 OpenGL ES 应 用 可 以 支持 触 控 交 互 
的 关键 点 在 于 ， 拓 展 GLSurfaceView 的 实现 ， 重 写 onTouchEvent() 方 法 来 监听 触摸 事件 。 


这 节 课 将 会 向 你 展示 如 何 监听 触 控 事件 ， 让 用 户 旋转 一 个 OpenGL ES 对 象 。 
AL a 
BC B fp dx 33 Up 2s 
为 了 让 我 们 的 OpenGL ES 应 用 响应 触 控 事件 ， 我 们 必须 实现 GLSurfaceView 类 中 的 


onTouchEvent() 方 法 。 下 面 的 例子 展示 了 如 何 监听 MotionEvent.ACTION_MOVE 事 件 ， 并 将 
事件 转换 为 形状 旋转 的 角度 : 


private final float TOUCH SCALE FACTOR = 180.0f / 320; 
private float mPreviousX; 
private float mPreviousY; 


@Override 

public boolean onTouchEvent(MotionEvent e) { 
// MotionEvent reports input details from the touch screen 
// and other input controls. In this case, you are only 
// interested in events where the touch position changed. 


float x 
float y 


e.getX(); 
e.getY(); 


switch (e.getAction()) { 
case MotionEvent.ACTION MOVE: 


float dx - x - mPreviousX; 
float dy 


y - mPreviousY; 


// reverse direction of rotation above the mid-line 
if (y > getHeight() / 2) { 
dx = dx * -1 ; 


// reverse direction of rotation to left of the mid-line 
if (x < getwidth() / 2) { 
dy = dy * -1 ; 


mRenderer .setAngle( 

mRenderer.getAngle() + 

((dx + dy) * TOUCH_SCALE_FACTOR) ); 
requestRender(); 


mPreviousX 


M 
x 


mPreviousY = y; 
recurn Erue; 


注意 在 计算 旋转 角度 后 ， 该 方法 会 调用 requestRender() 来 告诉 泻 染 器 现在 可 以 进行 泻 染 了 。 
这 种 办 法 对 于 这 个 例子 来 说 是 最 有 效 的 ， 因 为 图 形 并 不 需要 重新 绘制 ， 除 非 有 一 个 旋转 角度 
的 变化 。 当 然 ， 为 了 能 够 盟 正 实现 执行 效率 的 提高 ， 记 得 使 用 setRenderMode() 方 法 以 保证 泻 
染 器 仅 在 数据 发 生变 化 时 才 会 重新 绘制 图 形 ， 所 以 请 确保 这 一 行 代码 没有 被 注释 掉 : 


public MyGLSurfaceView(Context context) { 


// Render the view only when there is a change in the drawing data 
setRenderMode(GLSurfaceView.RENDERMODE WHEN DIRTY); 


公开 旋转 角度 


上 述 样 例 代码 需要 我 们 公开 旋转 的 角度 ， 具 体 来 说 ， 是 在 泻 染 器 中 添加 一 个 public 成 员 变 
量 。 由 于 演 染 器 代码 运行 在 一 个 独立 的 线程 中 ( 非 主 UI 线程 )， 我 们 必须 同时 将 该 变量 声明 
为 Volatile。 注 意 下 面 声 明 该 变量 的 代码 ， 另 外 对 应 的 get 和 set 方 法 也 被 声明 为 了 public mil 
函数 : 


public class MyGLRenderer implements GLSurfaceView.Renderer { 


public volatile float mAngle; 


public float getAngle() { 
return mAngle; 


public void setAngle(float angle) { 
mAngle - angle; 


应 用 旋转 


为 了 应 用 触 控 输 入 所 生成 的 旋转 ， 注 释 掉 创建 旋转 角度 的 代码 ， 然 后 添加 mangle ， 该 变量 包 
含 了 触 控 输 入 所 生成 的 角度 : 


public void ((GL10 gl) { 


float[] scratch - new float[16]; 


Matrix.setRotateM(mRotationMatrix, 0, mAngle, 0, 0, -1.0f); 


Matrix.multiplyMM(scratch, ©, mMVPMatrix, ©, mRotationMatrix, 9); 


mTriangle.draw(scratch); 


当 完 成 了 上 述 步 又 ， 我 们 就 可 以 运行 这 个 程序 ， 并 通过 手指 在 屏幕 上 的 滑动 旋转 三 角形 了 : 


è OpenGL ES 2.0 Complete 





添加 动画 


编写 :XizhiXu - 原文 :http://developer.android.com/training/animation/index.html 


动画 可 以 为 我 们 的 App 增 加 精细 的 视觉 提示 ， 并 且 能 改进 App 界 面 的 思维 模型 。 当 界面 改变 其 
状态 时 (例如 加 载 内 容 或 新 操作 可 用 时 ) ， 动 画 特别 有 帮助 。 另 外 ， 动 画 也 能 让 我 们 的 App 外 
观 更 加 优雅 ， 为 用 户 提供 一 种 更 好 的 使 用 体验 。 


但 是 记 住 : 滥用 动画 或 者 在 错误 时 机 使 用 动画 也 是 有 害 的 ， 比 如 他 们 会 造成 延迟 。 本 系列 课 
程 将 会 讲解 如 何 应 用 常用 动画 类 型 来 提升 易 用 性 。 我 们 的 目标 是 在 不 给 用 户 用 户 增 加 烦恼 的 
前 提 下 提升 App 的 “气质”。 


Lessons 


e View 间 渐变 


学 习 在 重 登 View 间 的 淡 入 淡出 。 作 为 一 个 例子 ， 我 们 将 会 学 习 如 何在 一 个 进度 条 与 一 个 
包含 了 文本 内 容 的 View 之 间 实 现 淡 入 淡出 的 效果 。 


e 用 ViewPager 实 现 屏 幕 滑 动 
学 习 怎 样 为 水 平 相 令 的 界面 提供 滑动 动画 。 
e 展示 Card 翻 转动 画 
学 习 怎 样 实现 两 个 View 之 间 的 翻转 动画 。 
e 缩放 View 
学 习 怎 样 通 过 触 控 放大 一 个 View © 
。 布局 变更 动画 


学 习 在 增加 、 移 除 或 更 新 子 View 时 ， 怎 样 使 用 内 置 的 动画 效果 。 


View 间 渐变 


编写 :XizhiXu - Æ x-:http://developer.android.com/training/animation/crossfade.html 
渐变 动画 (也 叫 消失 ) 通常 指 渐渐 的 淡出 某 个 UI 组 件 ， 同 时 同步 地 淡 入 另 一 个 。 当 App 想 切换 
内 容 或 View 的 情况 下 ， 这 种 动画 很 有 用 。 渐 变 简 短 不 多 察觉 ， 同 时 又 提供 从 一 个 界面 到 下 一 
个 之 间 流 畅 的 转换 。 如 果 在 需要 转换 的 时 候 没有 使 用 任何 动画 效果 ， 这 会 使 得 转换 看 上 去 感 
到 生硬 而 仓促 。 


下 面 是 一 个 利用 进度 指示 渐变 到 一 些 文本 内 容 的 例子 。 





如 果 你 想 跳 过 这 部 分 介绍 直接 查看 样 例 ， 下 载 并 运行 样 例 App 然 后 选择 渐变 例子 。 查 看 下 列 文 
件 中 的 代码 实现 : 


* src/CrossfadeActivity.java 
*  layout/activity crossfade.xml 


*  menu/activity crossfade.xml 


创建 View 


创建 两 个 我 们 想 相 互 渐变 的 View。 下 面 的 例子 创建 了 一 个 进度 提示 圈 和 可 滑动 文本 View 。 


«FrameLayout xmlns:android-"/apk/res/android" 
android: layout_width="match_parent" 
android: layout_height="match_parent"> 


«ScrollView xmlns:android="/apk/res/android" 
android:id="@+id/content" 
android: layout_width="match_parent" 
android: layout_height="match_parent"> 


«TextView style="?android: textAppearanceMedium" 
android: lineSpacingMultiplier="1.2" 
android: layout_width="match_parent" 
android: layout_height="wrap_content" 
android: text="@string/lorem_ipsum" 
android: padding="16dp" /> 


</ScrollView> 

<ProgressBar android: id="@+id/loading_spinner" 
style-"?android:progressBarStyleLarge" 
android: layout_width="wrap_content" 
android: layout_height="wrap_content" 


android: layout_gravity="center" /> 


</FrameLayout> 


DE BL 1) 


为 设置 动画 ， 我 们 需要 按照 如 下 步骤 来 做 : 


1. 为 我 们 想 渐 变 的 View 创建 成 员 变 量 。 在 之 后 动画 应 用 途中 修改 View 的 时 候 我 们 会 需要 记 


些 引 用 。 


iX 


2， 对 于 被 淡 入 的 View， 设 置 它 的 visibility 为 cone 。 这 样 防止 view 再 占据 布局 的 空间 ， 而 且 


也 能 在 布局 计算 中 将 其 忽略 ， 加 速 处 理 过 程 。 


3. 将 config shortanimrime 系统 属性 斩 存 到 一 个 成 员 变量 里 。 这 个 属性 为 动画 定义 了 一 个 标 
准 的 " 短 "持续 时 间 。 对 于 细微 或 者 快速 发 生 的 动画 ， 这 是 个 很 理想 的 持续 时 段 。 也 可 以 根 


据 实 际 需 求 使 用 config longAnimTime 或 config mediumAnimTime ° 


下 面 的 例子 使 用 了 前 文 提 到 的 布局 文件 : 


public class CrossfadeActivity extends Activity { 


private View mContentView; 
private View mLoadingView; 
private int mShortAnimationDuration; 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
setContentView(R.layout.activity crossfade); 


mContentView - findViewById(R.id.content); 
mLoadingView - findViewById(R.id.loading spinner); 


// Initially hide the content view. 
mContentView.setVisibility(View.GONE); 


// Retrieve and cache the system's default "short" animation time. 


mShortAnimationDuration = getResources().getInteger( 
android.R.integer.config shortAnimTime); 


à "t View 
进行 了 上 述 配 置 之 后 ， 接 下 来 就 让 我 们 实现 渐变 动画 吧 : 


1， 对 于 正在 淡 入 的 View， 设 置 它 的 alpha 值 为 0 并 且 设 置 visibility 为 VISIBLE ( 记 住 他 起 初 被 
设置 成 了 cone ) 。 这 样 View 就 变 成 可 见 的 了 ， 但 是 此 时 它 是 透明 的 。 

2， 对 于 正在 淡 入 的 View， 把 alpha 值 从 0 动态 改变 到 1。 同 时， 对 于 淡出 的 View， 把 alpha 值 
从 1 动态 变 到 0。 


3. 使 用 animator.AnimatorListener 中 的 onAnimationEnd() ， 设 置 淡 出 View 的 visibility 
为 cone 。 即 使 alpha 值 为 0， 也 要 把 View 的 visibility 设 置 成 cone 来 防止 view 占据 布局 空 
间 ， 还 能 把 它 从 布局 计算 中 和 忽略， 加 速 处 理 过 程 。 


详 见 下 面 的 例子 : 





private View mContentView; 
private View mLoadingView; 
private int mShortAnimationDuration; 


private void crossfade() { 


// Set the content view to 0% opacity but visible, so that it is visible 
// (but fully transparent) during the animation. 
mContentView.setAlpha(0f); 

mContentView.setVisibility(View.VISIBLE); 


// Animate the content view to 100% opacity, and clear any animation 
// listener set on the view. 
mContentView.animate() 

.alpha(if) 

.setDuration(mShortAnimationDuration) 

.setListener(null); 


// Animate the loading view to 0% opacity. After the animation ends, 
// set its visibility to GONE as an optimization step (it won't 
// participate in layout passes, etc.) 
mLoadingView.animate() 
.alpha(0f) 
.setDuration(mShortAnimationDuration) 
.setListener(new AnimatorListenerAdapter() ( 
@Override 
public void onAnimationEnd(Animator animation) { 
mLoadingView.setVisibility(View. GONE) ; 


3); 


使 用 ViewPager 实 现 屏幕 滑动 


编写 :XizhiXu - Æ x-:http://developer.android.com/training/animation/screen-slide.html 


屏幕 划 动 是 在 两 个 完整 界面 问 的 转换 ， 它 在 一 些 Ul 中 很 常见 ， 比 如 设置 向 导 和 幻灯 放映 。 这 
节 课 将 告诉 你 怎样 通过 Support library 提 供 的 viewPager 实现 屏幕 滑动 。 viewPager 能 自动 实 
现 屏幕 滑动 动画 。 下 面 展 示 了 从 一 个 内 容 界 面 到 一 下 界面 的 屏幕 滑动 转换 是 什么 样子 的 。 





如 果 你 想 直接 查看 整个 例子 ， 下 载 并 运行 App 样 例 然后 选择 屏幕 滑动 例子 。 查 看 下 列 文 件 中 的 
代码 实现 : 


* src/ScreenSlidePageFragment.java 
* 3src/ScreenSlideActivity.java 
e  layout/activity screen slide.xml 


*  layout/fragment screen slide page.xml 





创建 View 


创建 Fragment 所 使 用 的 布局 文件 。 下 面 的 例子 包含 一 个 显示 文本 的 TextView : 


«!-- fragment screen slide page.xml --> 

«ScrollView xmlns:android-"http://schemas.android.com/apk/res/android" 
android:id-"Q-id/content" 
android:layout width-"match parent" 
android:layout height-"match parent" > 


«TextView style="?android: textAppearanceMedium" 
android: padding="16dp" 
android: lineSpacingMultiplier="1.2" 
android: layout_width="match_parent" 
android: layout_height="wrap_content" 
android: text="@string/lorem_ipsum" /> 
</ScrollView> 


与 此 同时 我 们 还 定义 了 一 个 字符 串 作 为 该 Fragment 的 内 容 。 


创建 Fragment 


创建 一 个 Fragment 子 类 ， 它 从 oncreateview() 方法 中 返回 之 前 创建 的 布局 。 无 论 何 时 如 果 
我 们 需要 为 用 户 展示 一 个 新 的 页 面 ， 可 以 在 它 的 父 Activity 中 创建 该 Fragment 的 实例 : 


import android.support.v4.app.Fragment; 
public class ScreenSlidePageFragment extends Fragment { 


@Override 
public View onCreateView(LayoutInflater inflater, ViewGroup container, 
Bundle savedInstanceState) { 
ViewGroup rootView - (ViewGroup) inflater.inflate( 
R.layout.fragment screen slide page, container, false); 





return rootView; 


水 加 ViewPager 


viewPager 有 内 建 的 滑动 手势 用 来 在 页 面 间 转换 ， 并 且 它 默认 使 用 滑 屏 动画 ， 所 以 我 们 不 用 
自己 为 其 创建 ° ViewPager 使 用 PagerAdapter 来 补充 新 页 面 ? 所 以 PagerAdapter 会 用 到 你 之 
前 新 建 的 Fragment 类 。 


开始 之 前 ， 创 建 一 个 包含 viewPager 的 布局 : 


«!-- activity screen slide.xml --> 
«android.support.v4.view.ViewPager 
xmlns:android="http://schemas.android.com/apk/res/android" 
android: id="@+id/pager" 
android: layout_width="match_parent" 
android: layout_height="match_parent" /> 


创建 一 个 Activity 来 做 下 面 这 些 事情 : 
e 把 ContentView 设 置 成 这 个 包含 ViewPager 的 布局 。 


. 创建 一 个 继承 自 FragmentStatePagerAdapter 4h 象 类 的 类 ， 然 后 实现 getItem() 方法 来 
把 ScreenslidePageFragment 实例 作为 新 页 面 补 充 进 来 。PagerAdapter 还 需要 实 
HL getcount() 方法 ， 它 返回 Adapter 将 要 创建 页 面 的 总 数 (例如 5 个 ) © 


e 把 PagerAdapter 和 ViewPager 关联 起 来 。 


e 处 理 Back 按 钮 ， 按 下 变 为 在 虚拟 的 Fragment 栈 中 回 退 。 如 果 用 户 已 经 在 第 一 个 页 面 了 ， 
则 在 Activity 的 回 退 栈 (back stack) 中 回 退 。 


import android.support.v4.app.Fragment; 
import android.support.v4.app.FragmentManager; 


public class ScreenSlidePagerActivity extends FragmentActivity { 
SER 
* The number of pages (wizard steps) to show in this demo. 
a7, 
private static final int NUM_PAGES = 5; 


/** 
* The pager widget, which handles animation and allows swiping horizontally to ac 
cess previous 
* and next wizard steps. 
uu 
private ViewPager mPager; 


VENUE 

* The pager adapter, which provides the pages to the view pager widget. 
i 

private PagerAdapter mPagerAdapter; 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
setContentView(R.layout.activity screen slide); 


// Instantiate a ViewPager and a PagerAdapter. 

mPager - (ViewPager) findViewById(R.id.pager); 

mPagerAdapter = new ScreenSlidePagerAdapter(getSupportFragmentManager( )); 
mPager.setAdapter(mPagerAdapter); 


@Override 
public void onBackPressed() { 
if (mPager.getCurrentItem() == 0) { 


// If the user is currently looking at the first step, allow the system to 


handle the 
// Back button. This calls finish() on this activity and pops the back sta 
ck. 
super.onBackPressed(); 
} else { 
// Otherwise, select the previous step. 
mPager.setCurrentItem(mPager.getCurrentItem() - 1); 
} 
} 
/** 
* A simple pager adapter that represents 5 ScreenSlidePageFragment objects, in 
* sequence. 
By 
private class ScreenSlidePagerAdapter extends FragmentStatePagerAdapter { 
public ScreenSlidePagerAdapter(FragmentManager fm) { 
super(fm); 
} 
@Override 
public Fragment getItem(int position) { 
return new ScreenSlidePageFragment(); 
} 
@Override 
public int getCount() { 
return NUM PAGES; 
} 
} 
} 


用 PageTransformer 自 定义 动画 


要 展示 不 同 于 默认 滑 屏 效果 的 动画 ， 我 们 需要 实现 ViewPager.PageTransformer 接口 ， 然 后 把 
Wat AA ViewPager 4T 3 = RTE AGERET 155 + EN - HU 
换 ， 这 个 方法 都 会 为 每 个 可 见 页 面 (通常 只 有 一 个 页 面 可 见 ) 和 刚 消失 的 相 邻 页 面 调用 一 
次 。 例 如 ， 第 三 页 可 见 而 且 用 户 向 第 四 页 拖 动 ， transformpage() 在 操作 的 各 个 阶段 为 第 二 ， 
三 ， 四 页 分 别 调用 。 


在 transformPage( ) 的 实现 中 基于 当 前 屏幕 显示 的 页 面 的 position ( position 
由 transformPage() 方法 的 参数 给 出 ) 决定 哪些 页 面 需 要 被 动画 转换 ， 这 样 我 们 就 能 创建 自己 
的 动画 。 


position 参数 表示 特定 页 面相 对 于 屏幕 中 的 页 面 的 位 置 。 它 的 值 在 用 户 滑动 页 面 过 程 中 动态 
变化 。 当 某 一 页 面 填充 屏幕 ， 它 的 值 为 0。 当 页 面 刚 向 屏幕 右 侧 方向 被 拖 走 ， 它 的 值 为 1。 如 
果 用 户 在 页 面 1 和 页 面 2 问 滑动 到 一 半 ， 那 么 页 面 1 的 position 为 -0.5 并 且 页 面 2 的 position 为 
0.5。 根据 屏幕 上 页 面 的 position， 我 们 可 以 通 

过 setAlpha() ， setTranslationX() 或 setscalev() 这 些 方 法 设 定 页 面 属性 来 自 定义 滑动 动 


o 


也 | 


当 我 们 实现 了 pageTransformer 后 ， 用 我 们 的 实现 调用 setpageTransformer() 来 应 用 这 些 自 定 
义 动 画 。 例 如 ， 如 果 我 们 有 一 个 叫做 ZoomOutPageTransformer 的 PageTransformer ， 可 以 这 样 
设置 自 定义 动画 : 


ViewPager mPager = (ViewPager) findViewById(R.id.pager); 


mPager.setPageTransformer(true, new ZoomOutPageTransformer()); 


详情 查看 Zoom-out Page Transformerfe Depth Page Transformer 部 分 的 Pagerransformer 视 
频 和 例子 。 


Zoom-out Page Transformer 
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当 在 相 邻 界面 滑动 时 ， 这 个 Page Transformer 使 页 面 收缩 并 褪色 。 当 页 面 越 
渐渐 还 原 到 正常 大 小 并 且 图 像 渐 入 。 





public class ZoomOutPageTransformer implements ViewPager.PageTransformer { 
private static final float MIN SCALE - 0.85f; 
private static final float MIN ALPHA = 0.5f; 


public void transformPage(View view, float position) { 
int pageWidth = view.getWidth(); 
int pageHeight - view.getHeight(); 


if (position < -1) ( // [-Infinity, -1) 
// This page is way off-screen to the left. 
view.setAlpha(9); 


} else if (position <= 1) { // [-1,1] 
// Modify the default slide transition to shrink the page as well 
float scaleFactor = Math.max(MIN SCALE, 1 - Math.abs(position)); 
float vertMargin = pageHeight * (1 - scaleFactor) / 2; 
float horzMargin - pageWidth * (1 - scaleFactor) / 2; 
if (position < 0) ( 
view.setTranslationX(horzMargin - vertMargin / 2); 
) else { 
view.setTranslationX(-horzMargin + vertMargin / 2); 


// Scale the page down (between MIN SCALE and 1) 
view.setScaleX(scaleFactor); 
view.setScaleY(scaleFactor); 


// Fade the page relative to its size. 
view.setAlpha(MIN ALPHA + 

(scaleFactor - MIN SCALE) / 

(1 - MIN SCALE) * (i - MIN ALPHA)); 


) else { // (1,+Infinity] 


// This page is way off-screen to the right. 
view.setAlpha(9); 


Depth Page Transformer 


这 个 Page Transformer 使 用 默认 动画 的 屏幕 左 滑动 画 。 但 是 为 右 滑 使 用 一 种 “潜藏 "效果 的 动 
画 。 潜 藏 动画 将 page 淡 出 ， 并 且 线性 缩小 它 。 
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view.setTranslationX(-1 * view.getWidth() * position); 


下 面 的 例子 展示 了 如 何 抵消 默认 滑 屏 动画 : 
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public class DepthPageTransformer implements ViewPager.PageTransformer { 
private static final float MIN_SCALE = 0.75f; 


public void transformPage(View view, float position) { 
int pageWidth = view.getWidth(); 


if (position < -1) { // [-Infinity, -1) 
// This page is way off-screen to the left. 
view.setAlpha(9); 


} else if (position <= 0) ( // [-1,0] 
// Use the default slide transition when moving to the left page 
view.setAlpha(1); 
view.setTranslationX(9); 
view.setScaleX(1); 
view.setScaleY(1); 


} else if (position <= 1) ( // (0,1] 
// Fade the page out. 
view.setAlpha(i - position); 


// Counteract the default slide transition 
view.setTranslationX(pageWidth * -position); 


// Scale the page down (between MIN SCALE and 1) 
float scaleFactor - MIN SCALE 

+ (1 - MIN SCALE) * (1 - Math.abs(position)); 
view.setScaleX(scaleFactor); 
view.setScaleY(scaleFactor); 


else { // (1,+Infinity] 
// This page is way off-screen to the right. 
view.setAlpha(9); 
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展示 Card 翻 转动 画 


编写 :XizhiXu - 原文 :http://developer.android.com/training/animation/cardflip.html 


这 节 课 展示 如 何 使 用 自 定义 Fragment 动 画 实现 Card 翻 转动 画 。Card 翻 转动 画 通过 模拟 Card 翻 
转 的 效果 实现 view 内 容 的 切换 。 


下 面 是 card 翻 转动 画 的 样子 : 





如 果 你 想 直 接 查看 整个 例子 ， 下 载 并 运行 App 样 例 然 后 选择 Card 翻 转 例子 。 查 看 下 列 文件 中 
的 代码 实现 : 


*  src/CardFlipActivity.java 

*  animator/card flip right in.xml 
*  animator/card flip right out.xml 
*  animator/card flip left in.xml 

*  animator/card flip left out.xml 
*  layout/fragment card back.xml 


*  layout/fragment card front.xml 


4] 2 Animator 


创建 Card 翻 转动 画 ， 我 们 需要 两 个 Animator。 一 个 让 正面 的 card 的 右 侧 向 堪 翻转 渐 出 ， 一 个 
让 背面 的 Card 向 右 翻 转 渐 入 。 我 们 还 需要 两 个 Animator 让 背面 的 card 的 右 侧 向 左 翻 转 渐 入 ， 
一 个 让 向 右 翻 转 渐 入 。 


card flip left in.xml 


展示 Card 翻 转动 画 


«set xmlns:android="http://schemas.android.com/apk/res/android"> 


<!-- Before rotating, immediately set the alpha to ©. --> 
«objectAnimator 


android: valueFrom="1.0" 
android: valueTo="0.0" 
android: propertyName="alpha" 
android:duration="0" /> 


<!-- Rotate. --> 


<objectAnimator 


<!-- Half-way through the rotation (see startOffset), 


android: valueFrom="-180" 

android: valueTo="0" 

android: propertyName="rotationyY" 

android: interpolator="@android:interpolator/accelerate_decelerate" 
android:duration-"Qinteger/card flip time full" /> 


«objectAnimator 


«/set» 


android: valueFrom="0.0" 

android: valueTo="1.0" 

android: propertyName="alpha" 
android:startOffset-"Qinteger/card flip time half" 
android:duration-z"1" /> 


card flip left out.xml 


«set xmlns:android-"http://schemas.android.com/apk/res/android"» 
Eu spobudteum = 


«objectAnimator 


<!-- Half-way through the rotation (see startOffset), 


android: valueFrom="0" 

android: valueTo="180" 

android: propertyName="rotationy" 

android: interpolator="@android:interpolator/accelerate_decelerate" 
android:duration-"Qinteger/card flip time full" /> 


«objectAnimator 


«/set» 


android: valueFrom="1.0" 

android: valueTo="0.0" 

android: propertyName="alpha" 
android:startOffset-"Qinteger/card flip time half" 
android:duration="1" /> 


card_flip_right_in.xml 


set the alpha to 1. 


set the alpha to 0. 
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展示 Card 翻 转动 画 


«set xmlns:android-"http://schemas.android.com/apk/res/android"» 


<!-- Before rotating, immediately set the alpha to ©. --> 
«objectAnimator 


android: valueFrom="1.0" 
android: valueTo="0.0" 
android: propertyName="alpha" 
android:duration="0" /> 


<!-- Rotate. --> 


<objectAnimator 


<!-- Half-way through the rotation (see startOffset), 


android: valueFrom="180" 

android: valueTo="0" 

android: propertyName="rotationyY" 

android: interpolator="@android:interpolator/accelerate_decelerate" 
android:duration-"Qinteger/card flip time full" /> 


«objectAnimator 


«/set» 


android: valueFrom="0.0" 

android: valueTo="1.0" 

android: propertyName="alpha" 
android:startOffset-"Qinteger/card flip time half" 
android:duration="1" /> 


card flip right out.xml 


«set xmlns:android-"http://schemas.android.com/apk/res/android"» 
Eu spobudteum = 


«objectAnimator 


<!-- Half-way through the rotation (see startOffset), 


android: valueFrom="0" 

android: valueTo="-180" 

android: propertyName="rotationy" 

android: interpolator="@android:interpolator/accelerate_decelerate" 
android:duration-"Qinteger/card flip time full" /> 


«objectAnimator 


«/set» 


android: valueFrom="1.0" 

android: valueTo="0.0" 

android: propertyName="alpha" 
android:startOffset-"Qinteger/card flip time half" 
android:duration="1" /> 


创建 View 


set the alpha to 1. 


set the alpha to 0. 
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Card 的 每 一 面 是 一 个 独立 的 布局 ， 比 如 两 屏 文 字 ， 两 张 图 片 ， 或 者 任何 View 的 组 合 。 然 后 我 
们 将 在 应 用 动画 的 Fragment 里 面 用 到 这 两 个 布局 。 下 面 的 布局 创建 了 展示 文本 Card 的 一 面 : 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android: layout_width="match_parent" 
android: layout_height="match_parent" 
android: orientation="vertical" 
android: background="#a6c" 
android: padding="16dp" 
android: gravity="bottom"> 


<TextView android: id="@android:id/text1i" 
style="?android: textAppearanceLarge" 
android: textStyle="bold" 
android: textColor="#ffFf" 
android: layout_width="match_parent" 
android: layout_height="wrap_content" 
android:text-"Qstring/card back title" /> 


«TextView style-"?android:textAppearanceSmall" 
android:textAllCaps-"true" 
android:textColor-"Z80ffffff" 
android:textStyle-"bold" 
android: lineSpacingMultiplier="1.2" 
android: layout_width="match_parent" 
android: layout_height="wrap_content" 
android:text-"Qstring/card back description" /> 


</LinearLayout> 


Card 另 一 面 显示 一 个 ImageView 


«ImageView xmlns:android-"http://schemas.android.com/apk/res/android" 
android:layout width-"match parent" 
android:layout height-"match parent" 
android: src="@drawable/imagei" 
android: scaleType="centerCrop" 
android:contentDescription-"Qstring/description image 1" /> 


€| Fragment 


为 Card 正 反面 创建 Fragment， 这 些 类 从 oncreateview() 方法 中 分 别 为 每 个 Framgent 返 回 你 
之 前 创建 的 布局 。 在 想 要 显示 Card 的 父 Activity 中 ， 我 们 可 以 创建 对 应 的 Fragment 实例 。 下 面 
44 f| FJ a SC Activity A 4x ZA Fragment : 


public class CardFlipActivity extends Activity { 


/** 
* A fragment representing the front of the card. 
272 
public class CardFrontFragment extends Fragment { 
@Override 
public View onCreateView(LayoutInflater inflater, ViewGroup container, 
Bundle savedInstanceState) { 
return inflater.inflate(R.layout.fragment card front, container, false); 


/** 
* A fragment representing the back of the card. 
=f, 
public class CardBackFragment extends Fragment { 
@Override 
public View onCreateView(LayoutInflater inflater, ViewGroup container, 
Bundle savedInstanceState) { 
return inflater.inflate(R.layout.fragment card back, container, false); 


应 用 card 翻 转动 画 


现在 ， 我 们 需要 在 父 Activity 中 展示 Fragment。 为 此 ， 首 先 创建 Activity 的 布局 。 下 面 例子 创建 


了 一 个 可 以 在 运行 时 添加 Fragment 的 FrameLayout ° 


«FrameLayout xmlns:android="http://schemas.android.com/apk/res/android" 
android: id="@+id/container" 
android: layout_width="match_parent" 
android:layout height-"match parent" /> 


在 Activity 代 码 中 ， 把 先前 创建 的 布局 设置 成 其 ContentVew。 妆 Activity 创 建 时 展示 一 个 默认 的 


Fragment 是 个 不 错 的 注意 。 所 以 下 面 的 Activity 样 例 表 明了 如 何 默认 显示 卡片 正面 : 


public class CardFlipActivity extends Activity { 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


setContentView(R.layout.activity activity card flip); 


if (savedInstanceState == null) { 
getFragmentManager ( ) 

.beginTransaction() 

.add(R.id.container, 


new CardFrontFragment()) 
.commit(); 


既然 现在 显示 了 卡片 的 正面 ， 我 们 可 以 在 合适 时 机 用 翻转 动画 显示 卡片 背面 了 。 创 建 一 个 方 
法 来 显示 背面 ， 它 需要 做 下 面 这 些 事情 : 


e 将 Fragment 转 换 设置 我 们 刚 做 的 自 定 义 动画 
e 用 新 Fragment 替 换 当 前 显示 的 Fragment， 并 且 应 用 之 前 创建 的 动画 到 该 事件 中 。 


e 添加 之 前 显示 的 Fragment 到 Fragment 的 回 退 栈 (back stack) 中 ， 所 以 当 用 户 按 下 Back 
键 时 ，Card 会 翻转 回来 。 


展示 Card 翻 转动 画 


private void flipCard() { 
if (mShowingBack) { 
getFragmentManager ( ) . popBackStack( ); 
return; 
// Flip to the back. 
mShowingBack - true; 


// Create and commit a new fragment transaction that adds the fragment for the bac 


// the card, uses custom animations, and is part of the fragment manager's back st 


ack. 
getFragmentManager ( ) 
.beginTransaction() 
// Replace the default fragment animations with animator resources represe 
nting 
// rotations when switching to the back of the card, as well as animator 
// resources representing rotations when flipping back to the front (e.g. 
when 
// the system Back button is pressed). 
.setCustomAnimations( 
R.animator.card_flip_right_in, R.animator.card_flip_right_out, 
R.animator.card flip left in, R.animator.card flip left out) 
// Replace any fragments currently in the container view with a fragment 
// representing the next page (indicated by the just-incremented currentPa 
ge 
// variable). 
.replace(R.id.container, new CardBackFragment( )) 
// Add this transaction to the back stack, allowing users to press Back 
// to get to the front of the card. 
.addToBackStack(null) 
// Commit the transaction. 
.commit(); 
} 
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43 2X View 


编写 :XizhiXu - Æ x-:http://developer.android.com/training/animation/zoom.html 


这 节 课 展示 怎样 实现 点 击 缩放 动画 ， 这 对 相册 很 有 用 ， 他 能 为 相片 从 缩 略图 转换 成 原 图 并 卉 
充 屏 幕 提 供 动画 。 


下 面 展 示 了 触摸 缩放 动画 的 效果 ， 它 将 缩 略图 扩大 并 坊 充 屏幕 。 





如 果 你 想 直 接 查 看 整个 例子 ， 下 载 并 运行 App 样 例 然后 选择 缩放 的 例子 。 查 看 下 列 文件 中 的 代 
码 实 现 : 


Ar 


e src/TouchHighlightImageButton.java (简单 的 helper 类 ， 当 Image Button 被 按 下 它 显 示 蓝 
色 高 亮 ) 
* =6src/ZoomActivity.java 


*  layout/activity zoom.xml 


创建 View 


为 想 要 缩放 的 内 容 创 建 一 大 一 小 两 个 版 本 布局 文件 。 下 面 的 例子 为 可 点 击 的 缩 略图 新 建 了 一 


个 ImageButton 和 一 个 ImageView 来 展示 原 图 : 


缩放 View 


«FrameLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:id-"Q-id/container" 
android:layout width-"match parent" 
android: layout_height="match_parent"> 


<LinearLayout android:layout width-"match parent" 
android:layout height-"wrap content" 
android:orientation-"vertical" 
android:padding-"16dp"» 


«ImageButton 
android:id-"Q-id/thumb button 1" 
android: layout_width="100dp" 
android: layout_height="75dp" 
android: layout_marginRight="1dp" 
android: src="@drawable/thumbi" 
android: scaleType="centerCrop" 
android:contentDescription-"Qstring/description image 1" /> 


</LinearLayout> 


<!-- This initially-hidden ImageView will hold the expanded/zoomed version of 
the images above. Without transformations applied, it takes up the entire 
screen. To achieve the "zoom" animation, this view's bounds are animated 
from the bounds of the thumbnail button above, to its final laid-out 
bounds. 


Ses 


<ImageView 
android: id="@+tid/expanded_image" 
android: layout_width="match_parent" 
android:layout height-"match parent" 
android: visibility="invisible" 
android:contentDescription-"Qstring/description zoom touch close" /> 


«/FrameLayout» 


一 旦 实现 了 布局 ， 我 们 需要 设置 触发 缩放 动画 的 事件 handler。 下 面 的 例子 为 ImageButton 添 
加 了 一 个 View.onClickListener ， 当 用 户 点 击 按 钮 时 它 执 行 放 大 动画 。 
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public class ZoomActivity extends FragmentActivity { 
// Hold a reference to the current animator, 
// so that it can be canceled mid-way. 
private Animator mCurrentAnimator; 


// The system "short" animation time duration, in milliseconds. This 
// duration is ideal for subtle animations or animations that occur 
// very frequently. 

private int mShortAnimationDuration; 


QOverride 

protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity zoom); 


// Hook up clicks on the thumbnail views. 


final View thumbiView - findViewById(R.id.thumb button 1); 
thumbiView.setOnClickListener(new View.OnClickListener() { 
@Override 
public void onClick(View view) { 
zoomImageFromThumb(thumbiView, R.drawable.image1); 


3); 
// Retrieve and cache the system's default "short" animation time. 


mShortAnimationDuration = getResources().getInteger ( 
android.R.integer.config shortAnimTime); 


缩放 View 
我 们 现在 需要 适时 应 用 放大 动画 了 。 通 常 来 说 ， 我们 需要 按 边 界 来 从 小 号 View 放 大 到 大 号 
View。 下 面 的 方法 展示 了 如 何 实 现 缩放 动画 : 


1， 把 高 清 图 像 资 源 设置 到 已 经 被 隐藏 的 "放大 版 "的 Imageview 中 。 为 表 简 单 ， 下 面 的 例子 在 
UI 线 程 中 加 载 了 一 张大 图 。 但 是 我 们 需要 在 一 个 单独 的 线程 中 来 加 载 以 免 阻 塞 U 线 程 ， 
然后 再 回 到 UI 线程 中 设置 。 理 想 状况 下 ， 图 片 不 要 大 过 屏幕 尺寸 。 


2. 计算 Imageview 开始 和 结束 时 的 边界 。 


3， 从 起 始 边 到 结束 边 同 步 地 动态 改变 四 个 位 置 和 大 小 属性 x ，Y ( ScALEX 和 
SCALE Y ) 。 这 四 个 动画 被 加 入 到 了 Animatorset ， 所 以 我 们 可 以 让 它们 一 起 开始 。 


4. 缩小 则 运行 相同 的 动画 ， 但 是 是 在 用 户 点 击 屏幕 放大 时 的 逆向 效果 。 我 们 可 以 
在 Imageview 中 添加 一 个 view.onclickListener 来 实现 它 。 当 点 击 时 ， Imageview 缩 回 到 
原来 缩 略图 的 大 小 ， 然 后 设置 它 的 visibility 为 cone 来 隐藏 。 


private void zoomImageFromThumb(final View thumbView, int imageResId) { 
// If there's an animation in progress, cancel it 
// immediately and proceed with this one. 
if (mCurrentAnimator != null) { 
mCurrentAnimator.cancel(); 


// Load the high-resolution "zoomed-in" image. 

final ImageView expandedImageView - (ImageView) findViewById( 
R.id.expanded image); 

expandedImageView.setImageResource(imageResId); 


// Calculate the starting and ending bounds for the zoomed-in image. 
// This step involves lots of math. Yay, math. 


final Rect startBounds - new Rect(); 
final Rect finalBounds - new Rect(); 
final Point globaloffset = new Point(); 


// The start bounds are the global visible rectangle of the thumbnail, 
// and the final bounds are the global visible rectangle of the container 
// view. Also set the container view's offset as the origin for the 
// bounds, since that's the origin for the positioning animation 
// properties (X, Y). 
thumbView.getGlobalVisibleRect(startBounds); 
findViewById(R.id.container) 

.getGlobalVisibleRect(finalBounds, globalOffset); 
startBounds.offset(-globalOffset.x, -globalOffset.y); 
finalBounds.offset(-globalOffset.x, -globalOffset.y); 


// Adjust the start bounds to be the same aspect ratio as the final 
// bounds using the "center crop" technique. This prevents undesirable 
// stretching during the animation. Also calculate the start scaling 
// factor (the end scaling factor is always 1.0). 
float startScale; 
if ((float) finalBounds.width() / finalBounds.height() 
> (float) startBounds.width() / startBounds.height()) ( 
// Extend start bounds horizontally 
startScale - (float) startBounds.height() / finalBounds.height(); 
float startWidth - startScale * finalBounds.width(); 
float deltawidth = (startWidth - startBounds.width()) / 2; 
startBounds.left -= deltawidth; 
startBounds.right += deltawidth; 
} else { 
// Extend start bounds vertically 
startScale - (float) startBounds.width() / finalBounds.width(); 
float startHeight - startScale * finalBounds.height(); 
float deltaHeight - (startHeight - startBounds.height()) / 2; 
startBounds.top -- deltaHeight; 


startBounds.bottom += deltaHeight; 


// Hide the thumbnail and show the zoomed-in view. When the animation 
// begins, it will position the zoomed-in view in the place of the 

// thumbnail. 

thumbView.setAlpha(0f); 
expandedImageView.setVisibility(View.VISIBLE); 


// Set the pivot point for SCALE X and SCALE Y transformations 
// to the top-left corner of the zoomed-in view (the default 
// is the center of the view). 
expandedImageView.setPivotX(0f); 
expandedImageView.setPivotY(0f); 


// Construct and run the parallel animation of the four translation and 
// scale properties (X, Y, SCALE X, and SCALE Y). 
AnimatorSet set - new AnimatorSet(); 
set 
.play(ObjectAnimator.ofFloat(expandedImageView, View.X, 
startBounds.left, finalBounds.left)) 
.with(ObjectAnimator.ofFloat(expandedImageView, View.Y, 
startBounds.top, finalBounds.top)) 
.with(ObjectAnimator.ofFloat(expandedImageView, View.SCALE X, 
startScale, if)).with(ObjectAnimator.ofFloat(expandedImageView, 
View.SCALE Y, startScale, if)); 
set.setDuration(mShortAnimationDuration); 
set.setInterpolator(new DecelerateInterpolator()); 
set.addListener(new AnimatorListenerAdapter() { 
@Override 
public void onAnimationEnd(Animator animation) { 
mCurrentAnimator = null; 


@Override 
public void onAnimationCancel(Animator animation) { 
mCurrentAnimator - null; 


1; 
set.start(); 


mCurrentAnimator - set; 


// Upon clicking the zoomed-in image, it should zoom back down 

// to the original bounds and show the thumbnail instead of 

// the expanded image. 

final float startScaleFinal = startScale; 
expandedImageView.setOnClickListener(new View.OnClickListener() ( 


@Override 
public void onClick(View view) { 
if (mCurrentAnimator != null) { 


mCurrentAnimator.cancel(); 


3) 


// Animate the four positioning/sizing properties in parallel, 
// back to their original values. 
AnimatorSet set - new AnimatorSet(); 
set.play(ObjectAnimator 
.ofFloat(expandedImageView, View.X, startBounds.left)) 
.With(ObjectAnimator 
.ofFloat(expandedImageView, 
View.Y,startBounds.top)) 
.with(ObjectAnimator 
.ofFloat(expandedImageView, 
View.SCALE X, startScaleFinal)) 
.With(ObjectAnimator 
.ofFloat(expandedImageView, 
View.SCALE Y, startScaleFinal)); 
set.setDuration(mShortAnimationDuration); 
set.setInterpolator(new DecelerateInterpolator()); 
set.addListener(new AnimatorListenerAdapter() 1 
@Override 
public void onAnimationEnd(Animator animation) { 
thumbView.setAlpha(if); 
expandedImageView. setVisibility(View. GONE) ; 
mCurrentAnimator = null; 


@Override 

public void onAnimationCancel(Animator animation) 1 
thumbView.setAlpha(1f); 
expandedImageView.setVisibility(View.GONE); 
mCurrentAnimator - null; 


3); 


set.start(); 
mCurrentAnimator = set; 


布局 变更 动画 


编写 :XizhiXu - 原文 :http://developer.android.com/training/animation/layout.html 
布局 动画 是 一 种 预 加 载 动画 ， 系 统 在 每 次 改变 布局 配置 时 运行 它 。 我 们 需要 做 的 仅 是 在 布局 
文件 里 设置 属性 告诉 Android 系 统 为 这 些 布局 的 变更 应 用 动画 ， 然 后 系统 的 默认 动画 便 会 执 
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下 面 的 例子 在 一 个 list 中 添加 一 项 的 默认 布局 动画 





如 果 你 想 直接 查看 整个 例子 ， 下 载 App 样 例 并 运行 然后 选择 布局 渐变 的 例子 。 查 看 下 列 文件 
中 的 代码 实现 : 


* src/LayoutChangesActivity.java 
*  layout/activity layout changes.xml 


*  menu/activity layout changes.xml 


创建 布局 


在 Activity 的 XML 布局 文件 中 ， 为 想 开 局 动画 的 布局 设置 android:animateLayoutchanges 属性 
为 true 。 例 如 : 


«LinearLayout android:id-z'"Q-id/container" 
android:animateLayoutChanges-"true" 


7> 


从 布局 中 添加 ， 更 新 或 删除 项 目 


现在 ， 我 们 需要 做 的 就 是 添加 ， 删 除 或 更 新 布局 里 的 项 目 ， 然 后 这 些 项 目 就 会 自动 显示 动 
E 


private ViewGroup mContainerView; 


private void addItem() { 


View newView; 


mContainerView.addView(newView, 0); 


Android 网 络 连接 与 云 服 务 


Android 网 络 连 接 与 云 服务 


编写 :kesenhoo - 原文 :http://developer.android.com/training/building-connectivity.html 
这 些 课程 介绍 如 何 让 我 们 的 app 连接 到 用 户 设备 之 外 的 世界 。 我 们 将 会 学 习 如 何 连接 到 这 个 
区 域 的 其 他 设备 ， 连 接 到 互联 网 ， 以 及 备份 和 同步 应 用 程序 数据 等 等 。 
无 线 连 接 设 备 - Connecting Devices Wirelessly 
如 何 使 用 网 络 服务 发 现 (Network Service Discovery) 找到 并 连接 当地 设备 ， 以 及 如 何 用 Wi- 
Fi 创建 点 对 点 连接 . 
执行 网 络 操作 - Performing Network Operations 
如 何 创建 一 个 网 络 连 接 ， 监 视 连接 的 变化 ， 以 及 使 用 XML 数据 执行 事务 . 
传输 数据 时 避免 消耗 大 量 电 量 - Transferring Data Without 
Draining the Battery 


如 何在 app 执行 下 载 和 其 他 网 络 事务 时 最 小 化 对 电池 的 消耗 。 
云 同步 - Syncing to the Cloud 
如 何 同步 和 备份 应 用 程序 和 用 户 数据 到 云 中 的 远程 Web 服 务 ， 以 及 如 何 恢复 数据 到 多 个 设备 。 


解决 云 同 步 的 保存 冲突 : Resolving Cloud Save Conflicts 


如 何 为 app 设计 一 个 健壮 的 存储 数据 到 云 的 冲突 解决 策略 。 


使 用 Sycn Adapter 传 输 数 据 - Transferring Data Using Sync 
Adapters 

如 何 使 用 Android sync adapter 框架 在 云 和 设备 间 传 输 数 据 。 

使 用 Volley 传 输 网 络 数据 - Transmitting Network Data Using 
Volley 


如 何 使 用 Volley 通过 网 络 执行 快速 可 扩展 的 UI 操作 。 
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Android 网 络 连接 与 云 服务 
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无 线 连 授 设 备 


编写 :acenodie - 原文 :http://developer.android.com/training/connect-devices- 


wirelessly/index.html 


除了 能 够 在 云端 通信 ，Android 的 无 线 API 也 允许 同一 局 域 网 中 的 设备 进行 通信 ， 其 至 没有 连 
接 到 网 络 上 ， 而 是 物理 上 隔 得 很 近 ， 也 可 以 相互 通信 。 此 外 ， 网 络 服务 发 现 (Network 
Service Discovery， 简 称 NSD) 可 以 进一步 通过 允许 应 用 程序 运行 能 相互 通信 的 服务 去 寻找 
附近 运行 相同 服务 的 设备 。 把 这 个 功能 整合 到 我 们 的 应 用 中 ， 可 以 提供 许多 功能 ， 如 在 同一 
个 房间 ， 用 户 玩 游戏 ， 可 以 利用 NSD 实现 从 一 个 网 络 摄像 头 获取 图 像 ， 或 远程 登录 到 在 同一 
网 络 中 的 其 他 机 器 。 


本 节 课 介绍 了 一 些 使 我 们 的 应 用 程序 能 够 寻找 和 连接 其 他 设备 的 主要 AP|。 具 体 地 说 ， 它 介绍 
了 用 于 发 现 可 用 服务 的 NSD API 和 能 实现 点 对 点 无 线 连接 的 无 线 点 对 点 (the Wi-Fi Peer-to- 
Peer， 简 称 Wi-Fi P2P) API。 本 节 课 也 将 告诉 我 们 怎样 将 NSD 和 Wi-Fi P2P 结合 起 来 去 检 
测 其 他 设备 所 提供 的 服务 。 当 检测 到 时 ， 连 接 到 相应 的 设备 上 。 即 使 设备 都 没有 连接 到 一 个 
网 络 中 。 


Lessons 


使 用 网 络 服务 发 现 


学 习 如 何 广 播 由 我 们 自己 的 应 用 程序 提供 的 服务 ， 如 何 发 现在 本 地 网 络 上 提供 的 服务 ， 并 用 
NSD 获取 我 们 将 要 连接 的 服务 的 详细 信息 。 


使 用 WiFi 建立 P2P 连接 


学 习 如 何 获取 附近 的 对 等 设备 ， 如 何 创 建 一 个 设备 接 入 点 ， 如 何 连接 到 其 他 具有 Wi-Fi P2P 
连接 功能 的 设备 。 


使 用 WiFi P2P 发 现 服务 


学 习 如 何 使 用 WiFi P2P 服务 去 发 现 附近 的 不 在 同一 个 网 络 的 服务 。 


使 用 网 络 服务 发 现 


编写 :naizhengtan - 原文 :http://developer.android.com/training/connect-devices- 


wirelessly/nsd.html 


添加 网 络 服务 发 现 (Network Service Discovery) 到 我 们 的 app 中 ， 可 以 使 我 们 的 用 户 辨 识 
在 局 域 网 内 支持 我 们 的 app 所 请 求 的 服务 的 设备 。 这 种 技术 在 点 对 点 应 用 中 能 够 提供 大 量 帮 
助 ， 例 如 文件 共享 、 联 机 游戏 等 。Android 的 网 络 服务 发 现 (NSD) API 大 大 降低 实现 上 述 功 
能 的 难度 。 


本 讲 将 简要 介绍 如 何 创 建 NSD 应用， 使 其 能 够 在 本 地 网 络 内 广播 自己 的 名 称 和 连接 信息 ， 并 
且 扫 描 其 它 正 在 做 同样 事情 的 应 用 信息 。 最 后 ， 将 介绍 如 何 连接 运行 着 同样 应 用 的 另 一 台 设 
Bo 
AT NSD ARK 
Note: 这 一 步骤 是 选 做 的 。 如 果 我 们 并 不 关心 在 本 地 网 络 上 广播 app 服务 ， 那 么 我 们 可 
以 跳 过 这 一 步 ， 直 接 尝 试 发 现 网 络 中 的 服务 。 
在 局 域 网 内 注册 自己 服务 的 第 PER 32 NsdServicelnfo 对 象 。 此 对 象 包 信息 能 够 帮助 


网 络 中 的 其 他 设备 决定 是 否 要 连接 到 我 们 所 提供 的 服务 


public void registerService(int port) { 
// Create the NsdServiceInfo object, and populate it. 
NsdServiceInfo serviceInfo = new NsdServiceInfo(); 


// The name is subject to change based on conflicts 
// with other services advertised on the same network. 
serviceInfo.setServiceName("NsdChat"); 
serviceInfo.setServiceType(" http. tcp."); 
serviceInfo.setPort(port); 


这 段 代码 将 服务 命名 为 “NsdChat”。 该 名 称 将 对 所 有 局 域 网 络 中 使 用 NSD 查找 本 地 服务 的 设 

备 可 见 。 需 要 注意 的 是 ， 在 网 络 内 该 名 称 必须 是 独一无二 的 。Android 系统 会 自动 处 理 冲 突 的 

服务 名 称 。 如 果 同 时 有 两 个 名 为 “NsdChat” 的 应 用 ， 其 中 一 个 会 被 自动 转换 为 类 

似 *“NsdChat(1)”* 这 样 的 名 称 。 

第 二 个 参数 设置 了 服务 类 型 ， 即 指定 应 用 使 用 的 协议 和 传输 层 。 语 法 是 "< protocol >. < 

transportlayer >”。 在 上 面 的 代码 中 ， 服 务 使 用 了 TCP 协 议 上 的 HTTP 协 议 。 想 要 提供 打印 服务 
(例如 ， 一 台 网 络 打印 机 ) 的 应 用 应 该 将 服务 的 类 型 设置 为 ”ipp. tcp”。 


Note: 互联 网 编号 分 配 机 构 (International Assigned Numbers Authority， 简 称 IANA) 
提供 用 于 服务 发 现 协议 〈 例 如 NSD 和 Bonjour) 的 官方 服务 种 类 列表 。 我 们 可 以 下 载 该 
列表 了 解 相应 的 服务 名 称 和 端口 号 码 。 如 果 我 们 想起 用 新 的 服务 种 类 ， 应 该 向 IANA E 


方 提交 申请 。 


当 为 我 们 的 服务 设置 端口 号 时 ， 应 该 尽量 避免 将 其 硬 编码 在 代码 中 ， 以 防止 与 其 他 应 用 产生 
冲突 。 例 如 ， 如 果 我 们 的 应 用 仅仅 使 用 端口 1337， 就 可 能 与 其 他 使 用 1337 端 口 的 应 用 发 生 冲 
突 。 解 决 方法 是 ， 不 要 硬 编码 ， 使 用 下 一 个 可 用 的 端口 。 不 必 担 心 其 他 应 用 无 法 知晓 服务 的 
端口 号 ， 因 为 该 信息 将 包含 在 服务 的 广播 包 中 。 接 收 到 广播 后 ， 其 他 应 用 将 从 广播 包 中 得 知 
服务 端口 号 ， 并 通过 端口 连接 到 我 们 的 服务 上 。 


如 果 使 用 的 是 socket， 那 么 我 们 可 以 将 端口 设置 为 0， 来 初始 化 socket 到 任意 可 用 的 端口 。 
public void initializeServerSocket() { 


// Initialize a server socket on the next available port. 
mServerSocket = new ServerSocket(0); 


// Store the chosen port. 
mLocalPort = mServerSocket.getLocalPort(); 


现在 ， 我 们 已 经 成 功 的 创建 了 NsdServicelnfo 对 象 ， 接 下 来 要 做 的 是 实现 
RegistrationListener 接口 。 该 接口 包含 了 注册 在 Android 系统 中 的 回调 函数 ， 作 用 是 通知 应 
用 程序 服务 注册 和 注销 的 成 功 或 者 失败 。 





public void initializeRegistrationListener() { 
mRegistrationListener = new NsdManager.RegistrationListener() { 


@Override 

public void onServiceRegistered(NsdServiceInfo NsdServiceInfo) { 
// Save the service name. Android may have changed it in order to 
// resolve a conflict, so update the name you initially requested 
// with the name Android actually used. 
mServiceName - NsdServiceInfo.getServiceName(); 


@Override 
public void onRegistrationFailed(NsdServiceInfo serviceInfo, int errorcode) { 
// Registration failed! Put debugging code here to determine why. 


@Override 

public void onServiceUnregistered(NsdServiceInfo argo) { 
// Service has been unregistered. This only happens when you call 
// NsdManager.unregisterService() and pass in this listener. 


} 

@Override 

public void onUnregistrationFailed(NsdServiceInfo servicelnfo, int errorCode) 
t 

// Unregistration failed. Put debugging code here to determine why. 
} 
}; 

} 


万 事 俱 备 只 欠 东 风 ， 调 用 registerService() 方法 ， 申 正 注册 服务 。 


为 该 方法 是 异步 的 ， 所 以 在 服务 注册 之 后 的 操作 都 需要 在 onServiceRegistered() 方法 中 进 


a 
o 


public void registerService(int port) 1 
NsdServiceInfo serviceInfo = new NsdServiceInfo(); 
serviceInfo.setServiceName("NsdChat"); 
serviceInfo.setServiceType(" http. tcp."); 
serviceInfo.setPort(port); 


mNsdManager = Context.getSystemService(Context.NSD SERVICE); 


mNsdManager.registerService( 
serviceInfo, NsdManager.PROTOCOL DNS SD, mRegistrationListener); 


发 现 网 络 中 的 服务 
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网 络 充 斤 着 我 们 的 生活 ， 从 网 络 打印 机 到 网 络 摄像 头 ， 再 到 联网 并 字 棋 。 网 络 服务 发 现 是 能 
让 我 们 的 应 用 融入 这 一 切 功能 的 关键 。 我 们 的 应 用 需要 侦 听 网 络 内 服务 的 广播 ， 发 现 可 用 的 
服务 ， 过 滤 无 效 的 信息 。 


与 注册 网 络 服务 类 似 ， 服 务 发 现 需 要 两 步骤 : 用 相应 的 回调 函数 设置 发 现 监听 器 (Discover 
Listener) ， 以 及 调用 discoverServices() &*+# WAPI » 


首先 ， 实 例 化 一 个 实现 NsdManager.DiscoveryListener 接口 的 匿名 类 。 下 列 代码 是 一 个 简单 
的 范例 : 


public void initializeDiscoveryListener() { 


// Instantiate a new DiscoveryListener 
mDiscoveryListener = new NsdManager.DiscoveryListener() { 


// Called as soon as service discovery begins. 

@Override 

public void onDiscoveryStarted(String regType) { 
Log.d(TAG, "Service discovery started"); 


@Override 
public void onServiceFound(NsdServiceInfo service) { 
// A service was found! Do something with it. 
Log.d(TAG, "Service discovery success" + service); 
if (!service.getServiceType().equals(SERVICE_TYPE)) { 
// Service type is the string containing the protocol and 
// transport layer for this service. 
Log.d(TAG, "Unknown Service Type: " + service.getServiceType()); 
) else if (service.getServiceName().equals(mServiceName)) { 
// The name of the service tells the user what they'd be 
// connecting to. It could be "Bob's Chat App". 
Log.d(TAG, "Same machine: " + mServiceName); 
) eise if (service.getServiceName().contains("NsdChat"))( 
mNsdManager.resolveService(service, mResolveListener); 


@Override 

public void onServiceLost(NsdServiceInfo service) { 
// When the network service is no longer available. 
// Internal bookkeeping code goes here. 
Log.e(TAG, "service lost" + service); 


@Override 
public void onDiscoveryStopped(String serviceType) { 
Log.i(TAG, "Discovery stopped: " + serviceType); 


@Override 


public void onStartDiscoveryFailed(String serviceType, int errorcode) { 
Log.e(TAG, "Discovery failed: Error code:" + errorCode); 
mNsdManager .stopServiceDiscovery(this); 


} 


@Override 

public void onStopDiscoveryFailed(String serviceType, int errorCode) { 
Log.e(TAG, "Discovery failed: Error code:" + errorCode); 
mNsdManager .stopServiceDiscovery(this); 


NSD API 通过 使 用 该 接口 中 的 方法 通知 用 户 程 序 发 现 何 时 开始 、 何 时 失败 以 及 何 时 找到 可 用 
服务 和 何 时 服务 丢失 (丢失 意味 着 “不 再 可 用 ”) 。 在 上 述 代 码 中 ， 当 发 现 了 可 用 的 服务 时 ， 程 
序 做 了 几 次 检查 © 


1. 比较 找到 服务 的 名 称 与 本 地 服务 的 名 称 ， 判 断 设 备 是 否 获得 自己 的 〈 合 法 的 ) 广播 。 
2. 检查 服务 的 类 型 ， 确 认 这 个 类 型 我 们 的 应 用 是 否 可 以 接 入 。 
3， 检 查 服 务 的 名 称 ， 确 认 是 否 接 入 了 正确 的 应 用 。 


我 们 并 不 需要 每 次 都 检查 服务 名 称 ， 仅 当 我 们 想 要 接 入 特定 的 应 用 时 需要 检查 。 例 如 ， 应 用 
只 想 与 运行 在 其 他 设备 上 的 相同 应 用 通信 。 然 而 ， 如 果 应 用 仅仅 想 接 入 到 一 台 网 络 打印 机 ， 
那么 看 到 服务 类 型 是 "ipp. tcp” 的 服务 就 足够 了 。 


当 配 置 好 监听 器 后 ， 调 用 discoverService() 函数 ， 其 参数 包括 试图 发 现 的 服务 种 类 、 发 现 使 
用 的 协议 P 以 及 上 一 步 创 建 的 监听 器 5 


mNsdManager .discoverServices( 
SERVICE TYPE, NsdManager.PROTOCOL DNS SD, mDiscoveryListener); 


连接 到 网 络 上 的 服务 


当 我 们 的 应 用 发 现 了 网 上 可 接 入 的 服务 ， 首 先 需 要 调用 resolveService() 方法 ， 以 确定 服务 的 
连接 信息 。 实 现 NsdManager.ResolveListener 对 象 并 将 其 传 入 resolveservice() 方法 ， 并 
使 用 这 个 NsdManager.ResolveListener 对 象 获得 包含 连接 信息 的 NsdSerServicelnfo。 


public void initializeResolveListener() { 
mResolveListener = new NsdManager.ResolveListener() ( 


@Override 

public void onResolveFailed(NsdServiceInfo serviceInfo, int errorCode) { 
// Called when the resolve fails. Use the error code to debug. 
Log.e(TAG, "Resolve failed" + errorCode); 


@Override 
public void onServiceResolved(NsdServiceInfo serviceInfo) { 
Log.e(TAG, "Resolve Succeeded. " + serviceInfo); 


if (serviceInfo.getServiceName().equals(mServiceName)) ( 
Log.d(TAG, "Same IP."); 
return; 


j 


mService - serviceInfo; 
int port - mService.getPort(); 
InetAddress host - mService.getHost(); 


当 服 务 解析 完成 后 ， 我 们 将 获得 服务 的 详细 资料 ， 其 IP 地 址 和 端口 号 。 此 时 ， 我 们 就 可 
以 创建 自己 网 络 连接 与 服务 进行 通讯 。 


当 程 序 退 出 时 注销 服务 


在 应 用 的 生命 周期 中 正确 的 开启 和 关闭 NSD 服务 是 十 分 关键 的 。 在 程序 退出 时 注销 服务 可 以 
防止 其 他 程序 因为 不 知道 服务 退出 而 反复 尝试 连接 的 行为 。 另 外 ， 服 务 发 现 是 一 种 开销 很 大 

的 操作 ， 应 该 随 着 父 Activity 的 暂停 而 停止 ， 当 用 户 返回 该 界面 时 再 开启 。 因 此 ， 开 发 者 应 该 
重 写 Activity 的 生命 周期 函数 ， 并 添加 按照 需要 开启 和 停止 服务 广播 和 发 现 的 代码 。 


//In your application's Activity 


@Override 
protected void onPause() { 
if (mNsdHelper != null) { 
mNsdHelper .tearDown(); 


} 
super.onPause(); 
} 
@Override 


protected void onResume() { 
super .onResume(); 
if (mNsdHelper != null) { 
mNsdHelper.registerService(mConnection.getLocalPort()); 
mNsdHelper.discoverServices(); 


@Override 

protected void onDestroy() { 
mNsdHelper.tearDown(); 
mConnection.tearDown(); 
super.onDestroy(); 


// NsdHelper's tearDown method 
public void tearDown() { 
mNsdManager.unregisterService(mRegistrationListener); 
mNsdManager.stopServiceDiscovery(mDiscoveryListener); 


使 用 WiFi 建立 P2P 连接 


编写 :naizhengtan - 原文 :http://developer.android.com/training/connect-devices- 
wirelessly/wifi-direct.html 


Wi-Fi 点 对 点 (P2P) API 允许 应 用 程序 在 无 需 连 接 到 网 络 和 热点 的 情况 下 连接 到 附近 的 设 
备 。 (Android Wi-Fi P2P 使 用 Wi-Fi Direct™ 验证 程序 进行 编译 ) o Wi-Fi P2P 技术 使 得 应 
用 程序 可 以 快速 发 现 附近 的 设备 并 与 之 交互 。 相 比 于 蓝牙 技术 ，Wi-Fi P2P 的 优势 是 具有 较 大 
的 连接 范围 。 


本 节 主 要 内 容 是 使 用 Wi-Fi P2P 技术 发 现 并 连接 到 附近 的 设备 。 


置 应 用 权限 


使 用 Wi-Fi P2P 技术 ， 需 要 添加 CHANGE WIFI STATE * ACCESS WIFI STATE 以 及 
INTERNET 三 种 权限 到 应 用 的 manifest 文件 。Wi-Fi P2P 技术 虽然 不 需要 访问 互联 网 ， 但 是 
它 会 使 用 标准 的 Java socket ( $ INTERNET 权限 ) 。 下 面 是 使 用 Wi-Fi P2P 技术 需要 申 
请 的 权限 。 


«manifest xmlns:android-"http://schemas.android.com/apk/res/android" 
package="com.example.android.nsdchat" 


<uses-permission 

android: required="true" 

android: name="android.permission.ACCESS_WIFI_STATE"/> 
<uses-permission 

android: required="true" 

android: name="android.permission.CHANGE_WIFI_STATE"/> 
<uses-permission 

android: required="true" 

android: name="android. permission. INTERNET"/> 


设置 广播 接收 器 (BroadCast Receiver) 和 P2P 
管理 器 


使 用 Wi-Fi P2P 的 时 候 ， 需 要 侦 听 当 某 个 事件 出 现时 发 出 的 broadcast intent。 在 应 用 中 ， 实 
例 化 一 个 IntentFilter， 并 将 其 设置 为 侦 听 下 列 事件 : 


WIFI P2P. STATE CHANGED. ACTION 
指示 Wi-Fi P2P. 是 否 开局 
WIFI_P2P_PEERS_CHANGED_ACTION 
代表 对 等 节点 (peer) 列表 发 生 了 变化 
WIFI_P2P_CONNECTION_CHANGED_ACTION 
表明 Wi-Fi P2P 的 连接 状态 发 生 了 改变 
WIFI P2P. THIS DEVICE CHANGED ACTION 


指示 设备 的 详细 配置 发 生 了 变化 
private final IntentFilter intentFilter = new IntentFilter(); 


@Override 

public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState) ; 
setContentView(R.layout.main); 


// Indicates a change in the Wi-Fi P2P status. 
intentFilter.addAction(WifiP2pManager.WIFI P2P STATE CHANGED ACTION); 


// Indicates a change in the list of available peers. 
intentFilter.addAction(WifiP2pManager.WIFI P2P PEERS CHANGED ACTION); 


// Indicates the state of Wi-Fi P2P connectivity has changed. 
intentFilter.addAction(WifiP2pManager.WIFI P2P CONNECTION CHANGED ACTION); 


// Indicates this device's details have changed. 
intentFilter.addAction(WifiP2pManager.WIFI P2P THIS DEVICE CHANGED ACTION); 





在 onCreate() 方法 的 最 后 ， 需 要 获得 WifiPpManager 的 实例 ， 并 调用 它 的 ”initialize() 
方法 。 该 方法 将 返回 WifiP2pManager.Channel 对 象 。 我 们 的 应 用 将 在 后 面 使 用 该 对 但 连接 
Wi-Fi P2P 框架 。 


@Override 
Channel mChannel; 
public void onCreate(Bundle savedInstanceState) { 


mManager - (WifiP2pManager) getSystemService(Context.WIFI P2P SERVICE); 
mChannel - mManager.initialize(this, getMainLooper(), null); 


接 下 来 ， 创 建 一 个 新 的 BroadcastReceiver 类 侦 听 系统 中 Wi-Fi P2P 状态 的 变化 。 在 
onReceive() 方法 中 ， 加 入 对 上 述 四 种 不 同 P2P 状态 变化 的 处 理 。 


@Override 
public void onReceive(Context context, Intent intent) { 
String action = intent.getAction(); 
if (WifiP2pManager.WIFI P2P STATE CHANGED ACTION.equals(action)) { 
// Determine if Wifi P2P mode is enabled or not, alert 
// the Activity. 
int state = intent.getIntExtra(WifiP2pManager.EXTRA WIFI STATE, -1); 
if (state == WifiP2pManager.WIFI P2P STATE ENABLED) { 
activity.setIswifiP2pEnabled(true); 
} else { 
activity.setIswifiP2pEnabled( false); 


} else if (WifiP2pManager.WIFI P2P PEERS CHANGED ACTION.equals(action)) { 


// The peer list has changed! We should probably do something about 
// that. 


} else if (WifiP2pManager.WIFI P2P CONNECTION CHANGED ACTION.equals(action)) { 


// Connection state changed! We should probably do something about 
ia 


} else if (WifiP2pManager.WIFI P2P THIS DEVICE CHANGED ACTION.equals(action)) 





DeviceListFragment fragment = (DeviceListFragment) activity.getFragmentMan 
ager() 
.findFragmentById(R.id.frag list); 
fragment.updateThisDevice((WifiP2pDevice) intent.getParcelableExtra( 
WifiP2pManager .EXTRA_WIFI_P2P_DEVICE) ); 


最 后 ， 在 主 activity 开启 时 ， 加 入 注册 intent filter 和 broadcast receiver 的 代码 ， 并 在 activity 
暂停 或 关闭 时 ， 注 销 它们 。 上 述 做 法 最 好 放 在 onResume() 和 onPause() 方法 中 。 


/** register the BroadcastReceiver with the intent values to be matched */ 
@Override 
public void onResume() { 
super .onResume(); 
receiver = new WiFiDirectBroadcastReceiver(mManager, mChannel, this); 
registerReceiver(receiver, intentFilter); 


@Override 

public void onPause() { 
super .onPause(); 
unregisterReceiver (receiver); 


初始 化 对 等 节点 发 现 (Peer Discovery ) 


调用 discoverPeers() 开始 搜寻 附近 带 有 Wi-Fi P2P 的 设备 。 该 方法 需要 以 下 参数 : 


e 上 节 中 调用 WifiP2pManager 的 initialize() 函数 获得 的 WifiP2pManagerChannel 对 象 
e 一 个 对 WifiP2pManager.ActionListener 接口 的 实现 ， 包 括 了 当 系 统 成 功 和 失败 发 现 所 调 
用 的 方法 。 


mManager.discoverPeers(mChannel, new WifiP2pManager.ActionListener() { 


@Override 

public void onSuccess() { 
// Code for when the discovery initiation is successful goes here. 
// No services have actually been discovered yet, so this method 
// can often be left blank. Code for peer discovery goes in the 
// onReceive method, detailed below. 


@Override 

public void onFailure(int reasonCode) { 
// Code for when the discovery initiation fails goes here. 
// Alert the user that something went wrong. 


3); 
需要 注意 的 是 ， 这 仅仅 表示 对 Peer 发 现 Mind Discovery) 完成 初始 化 。discoverPeers() 7 
法 开启 了 发 现 过 程 并 且 立 即 返 回 。 系 统 会 通过 调用 WifiP2pManager.ActionListener 中 的 方法 


通知 应 用 对 oan o 同时， 对 等 节点 发 现 过 程 本 身 仍然 继续 运行 
直到 一 条 连接 或 者 一 个 P2P 小 组 建立 。 


获取 对 等 节点 列表 


在 完成 对 等 节点 发 现 过 程 的 初始 化 后 ， 我 们 需要 进一步 获取 附近 的 对 等 节点 列表 。 第 一 步 是 
实现 WifiP2pManager.PeerListListener 接口 。 该 接口 提供 了 Wi-Fi P2P 框架 发 现 的 对 等 节点 
信息 。 下 列 代 码 实现 了 相应 功能 : 


private List peers = new ArrayList(); 


private PeerListListener peerListListener = new PeerListListener() ( 
@Override 
public void onPeersAvailable(WifiP2pDeviceList peerList) { 


// Out with the old, in with the new. 
peers.clear(); 
peers.addAll(peerList.getDevicelist()); 


// If an AdapterView is backed by this data, notify it 
// of the change. For instance, if you have a ListView of available 
// peers, trigger an update. 
((WiFiPeerListAdapter) getListAdapter()).notifyDataSetChanged(); 
if (peers.size() == 0) { 
Log.d(WiFiDirectActivity.TAG, "No devices found"); 
return; 


4&' F3 > %-& Broadcast Receiver 的 onReceiver() 方法 。 当 收 到 

WIFI P2P PEERS CHANGED ACTION 事件 时 ， 调 用 requestPeer() 方法 获取 对 等 节点 列 
表 。 我 们 需要 将 WifiP2pManager.PeerListListener 传递 给 receiver。 一 种 方法 是 在 broadcast 
receiver 的 构造 函数 中 ， 将 对 象 作 为 参数 传 入 。 


public void onReceive(Context context, Intent intent) { 
else if (WifiP2pManager.WIFI P2P PEERS CHANGED ACTION.equals(action)) ( 


// Request available peers from the wifi p2p manager. This is an 
// asynchronous call and the calling activity is notified with a 
// callback on PeerListListener.onPeersAvailable() 
if (mManager !- null) { 

mManager.requestPeers(mChannel, peerListListener); 


} 
Log.d(WiFiDirectActivity.TAG, "P2P peers changed"); 


现在 ， 一 个 带 有 WIFI P2P. PEERS. CHANGED ACTION action 的 intent 将 触发 应 用 对 
Peer 列表 的 更 新 。 


连接 一 个 对 等 节点 


为 了 连接 到 一 个 对 等 节点 ， 我 们 需要 创建 一 个 新 的 WifiP2pConfig 对 象 ， 并 将 要 连接 的 设备 信 
息 从 表示 我 们 想 要 连接 设备 的 WifiP2pDevice 拷贝 到 其 中 。 然 后 调用 connect() 方法 。 


QOverride 

public void connect() { 
// Picking the first device found on the network. 
WifiP2pDevice device = peers.get(0); 


WifiP2pConfig config - new WifiP2pConfig(); 
config.deviceAddress - device.deviceAddress; 
config.wps.setup - WpsInfo.PBC; 


mManager.connect(mChannel, config, new ActionListener() { 


@Override 
public void onSuccess() { 
// WiFiDirectBroadcastReceiver will notify us. Ignore for now. 


@Override 
public void onFailure(int reason) ( 
Toast.makeText(WiFiDirectActivity.this, "Connect failed. Retry.", 
Toast.LENGTH SHORT).show(); 


3): 


在 本 段 代 码 中 的 WifiP2pManager.ActionListener 实现 仅 能 通知 我 们 初始 化 的 成 功 或 失败 。 想 
要 监听 连接 状态 的 变化 ， 需 要 实现 WifiP2pManager.ConnectionInfoListener 接口 。 接 口中 的 
onConnectionInfoAvailable() 回调 函数 会 在 连接 状态 发 生 改 变 时 通知 应 用 程序 。 当 有 多 个 设备 
同时 试图 连接 到 一 台 设 备 时 (例如 多 人 游戏 或 者 聊天 群 ) ， 这 一 台 设 备 将 被 指定 为 “ 群 

主 ”(group owner) 。 


@Override 


public void onConnectionInfoAvailable(final WifiP2pInfo info) { 


// InetAddress from WifiP2pInfo struct. 
InetAddress groupOwnerAddress = info.groupOwnerAddress.getHostAddress()); 


// After the group negotiation, we can determine the group owner. 
if (info.groupFormed && info.isGroupOwner) { 


// 
Z 
Ha 


Do whatever tasks are specific to the group owner. 

One common case is creating a server thread and accepting 
incoming connections. 

if (info.groupFormed) { 

The other device acts as the client. In this case, 

you'll want to create a client thread that connects to the group 


owner. 


此 时 ， 回 头 继续 完善 broadcast receiver 的 onReceive() 方法 ， 并 修改 对 

WIFI P2P CONNECTION CHANGED ACTION intent 的 监听 部 分 的 代码 。 当 接收 到 该 
intent 时 ， 调 用 requestConnectionInfo() 方法 。 此 方法 为 异步 ， 所 以 结果 将 会 被 我 们 提供 的 
WifiP2pManager.ConnectionInfoListener 所 获取 。 


) eise if (WifiP2pManager.WIFI P2P CONNECTION CHANGED ACTION.equals(action)) { 


if (mManager == null) { 


return; 


NetworkInfo networkInfo - (NetworkInfo) intent 


.getParcelableExtra(WifiP2pManager.EXTRA NETWORK INFO); 


if (networkInfo.isConnected()) { 


// We are connected with the other device, request connection 
// info to find group owner IP 


mManager.requestConnectionInfo(mChannel, connectionListener); 


使 用 WiFi P2P 服务 发 现 


编写 :naizhengtan - 原文 :http://developer.android.com/training/connect-devices- 
wirelessly/nsd-wifi-direct.html 


在 本 章 第 一 节 "“ 使 用 网 络 服务 发 现 " 中 介绍 了 如 何在 局 域 网 中 发 现 已 连接 到 网 络 的 服务 。 然 而 ， 
即使 在 不 接 入 网 络 的 情况 下 ，Wi-Fi P2P 服务 发 现 也 可 以 使 我 们 的 应 用 直接 发 现 附近 的 设备 。 
我 们 也 可 以 向 外 公布 自己 设备 上 的 服务 。 这 些 能 力 可 以 在 没有 局 域 网 或 者 网 络 热点 的 情况 

下 ， 在 应 用 间 进 行 通信 


o 


虽然 本 节 所 述 的 API 与 第 一 节 NSD (Network Service Discovery) 的 API 相似 ， 但 是 具体 的 
实现 代码 却 截然 不 同 。 本 节 将 讲述 如 何 通 过 Wi-Fi P2P 技术 发 现 其 它 设备 中 可 用 的 服务 。 本 
节 假 设 读者 已 经 对 Wi-Fi P2P 的 API 有 一 定 了 解 。 


配置 Manifest 


使 用 Wi-Fi P2P 技术 ， 需 要 添加 CHANGE _ WIFI STATE ` ACCESS WIFI STATE 以 及 
INTERNET 三 种 权限 到 应 用 的 manifest 文件 。 虽 然 Wi-Fi P2P 技术 不 需要 访问 互联 网 ， 但 是 
它 会 使 用 Java 中 的 标准 socket， 而 使 用 socket 需要 具有 INTERNET 权限 ， 这 也 是 Wi-Fi 
P2P 技术 需要 申请 该 权限 的 原因 。 


«manifest xmlns:android-"http://schemas.android.com/apk/res/android" 
package="com.example.android.nsdchat" 


<uses-permission 

android: required="true" 

android:name="android.permission.ACCESS_WIFI_STATE"/> 
<uses-permission 

android: required="true" 

android: name="android.permission.CHANGE_WIFI_STATE"/> 
<uses-permission 

android: required="true" 

android: name="android.permission. INTERNET"/> 


添加 本 地 服务 


如 果 我 们 想 提供 一 个 本 地 服务 ， 就 需要 在 服务 发 现 框架 中 注册 该 服务 。 当 本 地 服务 被 成 功 注 
册 ， 系 统 将 自动 回复 所 有 来 自 附近 的 服务 发 现 请 求 。 


三 步 创 建 本 地 服务 : 


1. #13 WifiP2pServicelnfo 对 象 
2， 加 入 相应 服务 的 详细 信息 
3. 调用 addLocalService() 为 服务 发 现 注 册 本 地 服务 


private void startRegistration() { 
// Create a string map containing information about your service. 
Map record - new HashMap(); 
record.put("listenport", String.valueOf(SERVER PORT)); 
record.put("buddyname", "John Doe" + (int) (Math.random() * 1000)); 
record.put("available", "visible"); 


// Service information. Pass it an instance name, service type 

// protocol. transportlayer , and the map containing 

// information other devices will want once they connect to this one. 

WifiP2pDnsSdServiceInfo serviceInfo - 
WifiP2pDnsSdServiceInfo.newInstance(" test", " presence. tcp", record) 


// Add the local service, sending the service info, network channel, 
// and listener that will be used to indicate success or failure of 
// the request. 
mManager.addLocalService(channel, serviceInfo, new ActionListener() { 
@Override 
public void onSuccess() { 
// Command successful! Code isn't necessarily needed here, 
// Unless you want to update the UI or add logging statements. 


@Override 
public void onFailure(int arg9) { 
// Command failed. Check for P2P_UNSUPPORTED, ERROR, or BUSY 


3); 


发 现 附 近 的 服务 


Android 使 用 回调 函数 通知 应 用 程序 附近 可 用 的 服务 ， 因 此 首先 要 做 的 是 设置 这 些 回调 函数 。 
新 建 一 个 WifiP2pManager.DnsSdTxtRecordListener 实例 监听 实时 收 到 的 记录 (record) ° 
这 些 记录 可 以 是 来 自 其 他 设备 的 广播 。 当 收 到 记录 时 ， 将 其 中 的 设备 地 址 和 其 他 相关 信息 找 
贝 到 当前 方法 之 外 的 外 部 数据 结构 中 ， 供 之 后 使 用 。 下 面 的 例子 假设 这 条 记录 包含 一 个 带 有 
用 户 身份 的 "buddyname” 域 (field) ° 


NO 





final HashMap<String, String> buddies = new HashMap<String, String>(); 


private void discoverService() { 
DnsSdTxtRecordListener txtListener - new DnsSdTxtRecordListener() ( 

@Override 

/* Callback includes: 
* fullDomain: full domain name: e.g "printer._ipp._tcp.local." 
* record: TXT record dta as a map of key/value pairs. 
* device: The device running the advertised service. 
sA 


public void onDnsSdTxtRecordAvailable( 
String fullDomain, Map record, WifiP2pDevice device) { 
Log.d(TAG, "DnsSdTxtRecord available -" + record.toString()); 
buddies.put(device.deviceAddress, record.get("buddyname")); 


un 


接 下 来 创建 WifiP2pManager.DnsSdServiceResponseListener 对 象 ， 用 以 获取 服务 的 信息 。 
这 个 对 象 将 接收 服务 的 实际 描述 以 及 连接 信息 。 上 一 段 代码 构建 了 一 个 包含 设备 地 址 

和 “buddyname” 键 值 对 的 Map 对 象 。WifiP2pManager.DnsSdServiceResponseListener 对 象 
使 用 这 些 配对 信息 将 DNS 记录 和 对 应 的 服务 信息 对 应 起 来 。 当 上 述 两 个 listener 构建 完成 

后 ， 调 用 setDnsSdResponseListeners() 将 他 们 加 入 到 WifiP2pManager ° 


private void discoverService() { 


DnsSdServiceResponseListener servListener = new DnsSdServiceResponseListener() { 
@Override 
public void onDnsSdServiceAvailable(String instanceName, String registrationTy 


pe, 
WifiP2pDevice resourceType) { 
// Update the device name with the human-friendly version from 
// the DnsTxtRecord, assuming one arrived. 
resourceType.deviceName = buddies 
.containsKey(resourceType.deviceAddress) ? buddies 
.get(resourceType.deviceAddress) : resourceType.deviceName; 
// Add to the custom adapter defined specifically for showing 
// wifi devices. 
WiFiDirectServicesList fragment = (WiFiDirectServicesList) getFragment 
Manager () 
.findFragmentById(R.id.frag peerlist); 
WiFiDevicesAdapter adapter - ((WiFiDevicesAdapter) fragment 
.getListAdapter()); 
adapter.add(resourceType); 
adapter.notifyDataSetChanged(); 
Log.d(TAG, "onBonjourServiceAvailable " + instanceName); 
} 
J; 


mManager .setDnsSdResponseListeners(channel, servListener, txtListener); 


现在 调用 addServiceRequest() 创建 服务 请 求 。 这 个 方法 也 需要 一 个 Listener 报告 请 求 成 功 
与 失败 。 


serviceRequest = WifiP2pDnsSdServiceRequest.newInstance(); 
mManager .addServiceRequest (channel, 
serviceRequest, 
new ActionListener() { 
@Override 
public void onSuccess() { 
// SUCCESS! 


@Override 
public void onFailure(int code) { 
// Command failed. Check for P2P_UNSUPPORTED, ERROR, or BUSY 


3); 


最 后 调用 discoverServices() ° 


mManager.discoverServices(channel, new ActionListener() ( 


@Override 
public void onSuccess() { 
M SUCCESS! 


$ 


@Override 
public void onFailure(int code) { 
// Command failed. Check for P2P UNSUPPORTED, ERROR, or BUSY 
if (code == WifiP2pManager.P2P UNSUPPORTED) { 
Log.d(TAG, "P2P isn't supported on this device."); 
else if(...) 


} 
3): 


如 果 所 有 部 分 都 配置 正确 ， 我 们 应 该 就 能 看 到 正确 的 结果 了 ! 如 果 遇 到 了 问题 ， 可 以 查看 
WifiP2pManager.ActionListener 中 的 回调 函数 。 它 们 能 够 指示 操作 是 否 成 功 。 我 们 可 以 将 
debug 的 代码 放置 在 onFailure() 中 来 诊断 问题 。 其 中 的 一 些 错误 码 (Error Code) 也 许 能 为 
我 们 带 来 不 小 启发 。 下 面 是 一 些 常见 的 错误 : 


P2P_UNSUPPORTED 

当前 的 设备 不 支持 Wi-Fi P2P 
BUSY 

系统 忙 ， 无 法 处 理 当 前 请 求 
ERROR 


内 部 错误 导致 操作 失败 


执行 网 络 操 作 


编写 :kesenhoo - 原文 :http://developer.android.com/training/basics/network- 
ops/index.html 


这 一 章 会 介绍 一 些 基 本 的 网 络 操作 ， 涉 及 到 网 络 连接 、 监 视 网 络 连接 (包括 网 络 改变 ) 和 证 
用 户 控制 app 的 网 络 用 途 。 还 会 介绍 如 何 解析 与 使 用 XML 数据 。 


这 节 课 包括 一 个 示例 应 用 ， 展 示 如 何 执行 常见 的 网 络 操作 。 我 们 可 以 下 载 下 面 的 的 范例 ， 并 
把 它 作 为 可 重用 代码 在 自己 的 应 用 中 使 用 。 


NetworkUsage.zip 


通过 学 习 这 章节 的 课程 ， 我 们 将 会 学 习 到 一 些 有 关于 如 何 创 建 一 个 使 用 最 少 的 网 络 流量 下 载 
并 解析 数据 的 高 效 app 的 基础 知识 。 


你 还 可 以 参考 下 面 文章 进 阶 学 习 : 


e Optimizing Battery Life 

e Transferring Data Without Draining the Battery 
e Web Apps Overview 

e Transmitting Network Data Using Volley 


Node: 查看 使 用 Volley 传输 网 络 数据 课程 获取 Volley 的 相关 信息 ， 它 是 一 个 能 帮助 
Android apps 更 方便 快捷 地 执行 网 络 操作 的 HTTP 库 。Volly 可 以 在 开源 AOSP 库 中 找 
Z] o Volly 可 能 会 帮助 我 们 简化 网 络 操作 ， 提 高 我 们 app 的 网 络 操作 性 能 。 


Lessons 


连接 到 网 络 - Connecting to the Network 

学 习 如 何 连接 到 网 络 ， 选 择 一 个 HTTP client > UA Ul 线程 外 执行 网 络 操 作 。 

管理 网 络 的 使 用 情况 - Managing Network Usage 

学 习 如 何 检查 设备 的 网 络 连接 情况 ， 创 建 偏 好 界面 来 控制 网 络 使 用 ， 以 及 响应 连接 变化 。 
解析 XML 数据 - Parsing XML Data 


学 习 如 何 解析 和 使 用 XML. 数据 。 


O 


p 


连 授 到 网 络 


编写 :kesenhoo - 原文 :http://developer.android.com/training/basics/network- 
ops/connecting.html 


这 一 课 会 演示 如 何 实现 一 个 简单 的 连接 到 网 络 的 程序 。 它 提供 了 一 些 我 们 在 创建 即使 最 简单 
的 网 络 连接 程序 时 也 应 该 遵循 的 最 佳 示例 。 


请 注意 ， 想 要 执行 本 课 的 网 络 操作 首先 需要 在 程序 的 manifest 文件 中 添加 以 下 权限 : 


«uses-permission android:name-"android.permission.INTERNET" /> 
«uses-permission android:name-"android.permission.ACCESS NETWORK STATE" /» 


选择 一 个 HTTP Client 


大 多 数 连接 网 络 的 Android app 会 使 用 HTTP 来 发 送 与 接收 数据 。Android 提供 了 两 种 HTTP 
clients : HttpURLConnection 4 Apache HttpClient。 二 者 均 支持 HTTPS、 流 媒体 上 传 和 下 
载 、 可 配置 的 超时 、IPv6 与 连接 池 (connection pooling) 。 对 于 Android 2.3 Gingerbread 
或 更 高 的 版 本 ， 推 荐 使 用 HttpURLConnection。 关 于 这 部 分 的 更 多 详情 ， 请 参考 Android's 
HTTP Clients ° 


检查 网 络 连接 


在 我 们 的 app 尝试 连接 网 络 之 前 ， 应 通过 函数 getActiveNetworklnfo() 和 isConnected() 检测 
当前 网 络 是 否 可 用 。 请 注意 ， 设 备 可 能 不 在 网 络 履 盖 范 围 内 ， 或 者 用 户 可 能 关闭 Wi-Fi 与 移动 
网 络 连接 。 关 于 这 部 分 的 更 多 详情 ， 请 参考 管理 网 络 的 使 用 情况 


public void myClickHandler(View view) { 


ConnectivityManager connMgr = (ConnectivityManager ) 
getSystemService(Context.CONNECTIVITY SERVICE); 
NetworkInfo networkInfo - connMgr.getActiveNetworkInfo(); 
if (networkInfo != null && networkInfo.isConnected()) { 
// fetch data 
) else { 
// display error 


} 


在 一 个 单独 的 线程 中 执行 网 络 操作 


网 络 操作 会 遇 到 不 可 预期 的 延迟 。 为 了 避免 造成 不 好 的 用 户 体 验 ， 总 是 在 UI 线程 之 外 单独 的 
线程 中 执行 网 络 操作 。AsyncTask 类 提供 了 一 种 简单 的 方式 来 处 理 这 个 问题 。 这 部 分 的 详 
情 ， 请 参考 Multithreading For Performance。 


在 下 面 的 代码 示例 中 ， myclickHandler() 方法 会 执行 new 
DownloadwebpageTask().execute(stringUrl) ° DownloadWebpageTask 是 AsyncTask 的 子 类 ， 它 
实现 了 下 面 两 个 方法 : 


e dolnBackground() 执行 downloadurl() 方法 。 它 以 网 页 的 URL. 作为 参数 ， 方 法 
downloadurl() 获取 并 处 理 网 页 返回 的 数据 。 执 行 完毕 后 ， 返 回 一 个 结果 字符 串 。 
e onPostExecute() 接收 结果 字符 囊 并 把 它 显示 到 UI 上。 


public class HttpExampleActivity extends Activity { 
private static final String DEBUG TAG = "HttpExample"; 
private EditText urlText; 
private TextView textView; 


@Override 

public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.main); 
urlText = (EditText) findViewById(R.id.myUr1); 
textView - (TextView) findViewById(R.id.myText); 


// When user clicks button, calls AsyncTask. 
// Before attempting to fetch the URL, makes sure that there is a network connecti 
on. 
public void myClickHandler(View view) { 
// Gets the URL from the UI's text field. 
String stringUrl - urlText.getText().toString(); 
ConnectivityManager connMgr - (ConnectivityManager) 
getSystemService(Context.CONNECTIVITY SERVICE); 
NetworkInfo networkInfo - connMgr.getActiveNetworkInfo(); 
if (networkInfo != null && networkInfo.isConnected()) ( 
new DownloadwebpageText().execute(stringUrl); 
else { 
textView.setText("No network connection available."); 


// Uses AsyncTask to create a task away from the main UI thread. This task takes a 


// URL string and uses it to create an HttpUrlConnection. Once the connection 

// has been established, the AsyncTask downloads the contents of the webpage as 
// an InputStream. Finally, the InputStream is converted into a string, which is 
// displayed in the UI by the AsyncTask's onPostExecute method. 


private class DownloadWebpageText extends AsyncTask { 
@Override 
protected String doInBackground(String... urls) { 


// params comes from the execute() call: params[0] is the url. 
try { 
return downloadUrl(urls[0]); 
} catch (IOException e) { 
return "Unable to retrieve web page. URL may be invalid."; 
} 
} 
// onPostExecute displays the results of the AsyncTask. 
@Override 
protected void onPostExecute(String result) { 
textView.setText(result); 


EE 
上 面 这 段 代码 的 事件 顺序 如 下 : 


1.， 当 用 户 点 击 按钮 时 调用 myclickHandler() > app 将 指定 的 URL 传 给 AsyncTask 的 子 类 
DownloadWebpageTask ° 

AsyncTask 的 dolnBackground() 方法 调用 downioaduri() 方法 。 

downloadurl() 方法 以 一 个 URL 字符 串 作为 参数 ， 并 用 它 创建 一 个 URL 对 象 。 

这 个 URL 对 象 被 用 来 创建 一 个 HttpURL Connection 。 

一 旦 建立 连接 ，HttpURLConnection 对 象 将 获取 网 页 的 内 容 并 得 到 一 个 InputStream 。 
InputStream 被 传 给 readit() 方法 ， 该 方法 将 流转 换 成 字符 串 。 

最 后 ，AsyncTask 的 onPostExecute() 方法 将 字符 串 展示 在 main activity 4 Ul 上 。 


NO a FWD 


连接 并 下 载 数 据 


在 执行 网 络 交互 的 线程 里 面 ， 我 们 可 以 使 用 HttpURLConnection 来 执行 一 个 GET 类 型 的 操 
作 并 下 载 数据 。 在 调用 conect) 之 后 ， 我 们 可 以 通过 调用 getrnputstream() 来 得 到 一 个 
包含 数据 的 InputStream 对 象 。 


在 下 面 的 代码 示例 中 ，dolnBackground() 方法 会 调用 downloadurl() 。 这 个 downloadUrl() 
方法 使 用 给 予 的 URL， 通 过 HttpURLConnection 连接 到 网 络 。 一 旦 建立 连接 后 ，app 就 会 使 
用 getInputstream() 来 获取 和 包含 数据 的 InputStream 。 


// Given a URL, establishes an HttpUrlConnection and retrieves 
// the web page content as a InputStream, which it returns as 
A SERING: 
private String downloadUrl(String myurl) throws IOException { 
InputStream is - null; 
// Only display the first 500 characters of the retrieved 
// web page content. 
int len - 500; 


try { 
URL url = new URL(myurl); 
HttpURLConnection conn - (HttpURLConnection) url.openConnection(); 
conn.setReadTimeout(10000 /* milliseconds */); 
conn.setConnectTimeout(15000 /* milliseconds */); 
conn.setRequestMethod( GET"); 
conn.setDoInput(true); 
// Starts the query 
conn.connect(); 
int response - conn.getResponseCode(); 
Log.d(DEBUG TAG, "The response is: " + response); 
is - conn.getInputStream(); 


// Convert the InputStream into a string 
String contentAsString - readIt(is, len); 
return contentAsString; 


// Makes sure that the InputStream is closed after the app is 
// finished using it. 
} finally { 
if (is != null) { 
is.close(); 


请 注意 ， getResponseCode() 会 返回 连接 的 状态 码 (status code) 。 这 是 一 种 获知 额外 网 络 连 
接 信息 的 有 效 方式 。 其 中 ， 状 态 码 是 200 则 意味 着 连接 成 功 。 


将 输入 流 (InputStream) 转换 为 字符 串 


(decode) 或 者 转换 为 目标 数据 类 型 。 例 如 ， 如 果 我 们 是 在 下 载 图 片 数据 ， 那 么 可 能 需要 像 
下 面 这 样 解码 并 展示 它 : 


InputStream is = null; 


Bitmap bitmap - BitmapFactory.decodeStream(is); 
ImageView imageView - (ImageView) findViewById(R.id.image view); 
imageView. setImageBitmap(bitmap) ; 


在 上 面 演示 的 示例 中 ，InputStream 包含 的 是 网 页 的 文本 内 容 。 下 面 会 演示 如 何 把 
InputStream 转换 为 字符 串 ， 以 便 显 示 在 Ul 上 。 


// Reads an InputStream and converts it to a String. 
public String readIt(InputStream stream, int len) throws IOException, UnsupportedEncod 
ingException { 

Reader reader - null; 

reader - new InputStreamReader(stream, "UTF-8"); 

char[] buffer = new char[len]; 

reader .read(buffer); 

return new String(buffer); 


管理 网 络 的 使 用 情况 


编写 :kesenhoo - 原文 :http://developer.android.com/training/basics/network- 
ops/managing.html 


这 一 课 会 介绍 如 何 细 化 管理 使 用 的 网 络 资源 。 如 果 我 们 的 程序 需要 执行 大 量 网 cue 那么 
应 该 提供 用 户 设置 选项 ， 来 允许 用 户 控制 程序 的 数据 偏好 。 例 如 ， 同 步 数 据 的 频率 ， 是 否 只 
在 连接 到 WiFi 才 进 行 下 载 与 上 传 操作 ， 是 否 在 漫游 时 使 用 套餐 数据 流量 等 等 s TT 
可 能 在 快 到 达 流 量 上 限时 ， 茜 止 我 们 的 程序 获取 后 台数 据 ， 因为 他们 可 以 精确 皖南 1 我 们 的 

app 使 用 多 少数 据 流量 。 


关于 如 何 编写 一 个 最 小 化 下 载 与 网 络 操作 对 电量 影响 的 程序 ， 请 参考 : 优化 电池 寿命 和 高 效 
下 载 。 


示例 : NetworkUsage.zip 


检查 设备 的 网 络 连接 


设备 可 以 有 许多 种 网 络 连接 。 这 节 课 主要 关注 使 用 Wi-Fi 或 移动 网 络 连接 的 情况 。 关 于 所 有 可 
能 的 网 络 连接 类 型 ， 请 看 ConnectivityManager 。 


通常 Wi-Fi 是 比较 快 的 。 移 动 数据 通常 都 是 需要 按 流量 计 费 ， 会 比较 贵 。 通 常 我 们 会 选择 让 
app 在 连接 到 WiFi 时 去 获取 大 量 的 数据 。 


在 执行 网 络 操作 之 前 ， 检 查 设 备 当 前 连接 的 网 络 连接 信息 是 个 好 习惯 。 这 样 可 以 防止 我 们 的 
程序 在 无 意 间 连接 使 用 了 非 意向 的 网 络 频道 。 如 果 网 络 连接 不 可 用 ， 那 么 我 们 的 应 用 应 该 优 
雅 地 做 出 响应 。 为 了 检测 网 络 连接 ， 我 们 需要 使 用 到 下 面 两 个 类 : 


e ConnectivityManager : 它 会 回答 关于 网 络 连 接 的 查询 结果 ， 并 在 网 络 连接 改变 时 通知 应 
用 程序 。 
e Networklnfo : 描述 一 个 给 定 类 型 (就 本 节 而 言 是 移动 网 络 或 Wi-Fi) 的 网 络 接口 状态 。 
这 段 代 码 检 查 了 Wi-Fi 与 移动 网 络 的 网 络 连 接 。 它 检查 了 这 些 网 络 接口 是 否 可 用 (也 就 是 说 网 
络 是 通 的 ) 及 是 否 已 连接 (也 就 是 说 网 络 连接 存在 ， 并 且 可 以 建立 socket 来 传输 数据 ) 


private static final String DEBUG TAG = "NetworkStatusExample"; 


ConnectivityManager connMgr = (ConnectivityManager ) 
getSystemService(Context.CONNECTIVITY SERVICE); 

NetworkInfo networkInfo - connMgr.getNetworkInfo(ConnectivityManager.TYPE WIFI); 

boolean isWifiConn - networkInfo.isConnected(); 

networkInfo - connMgr.getNetworkInfo(ConnectivityManager.TYPE MOBILE); 

boolean isMobileConn - networkInfo.isConnected(); 

Log.d(DEBUG TAG, "Wifi connected: " + isWifiConn); 

Log.d(DEBUG TAG, "Mobile connected: " + isMobileConn); 


请 注意 我 们 不 应 该 仅仅 靠 网 络 是 否 可 用 来 做 出 决策 。 由 于 isConnected() 能 够 处 理 片 状 移动 网 
络 (flaky mobile networks) ， 飞 行 模式 和 受 限 制 的 后 台数 据 等 情况 ， 所 以 我 们 应 该 总 是 在 执 
行 网 络 操作 前 检查 isConnected() ° 


一 个 更 简洁 的 检查 网 络 是 否 可 用 的 示例 如 下 。getActiveNetworklnfo() 方法 返回 一 个 
Networklnfo 实例 ， 它 表示 可 以 找到 的 第 一 个 已 连接 的 网 络 接口 ， 如 果 返 回 null， 则 表示 没有 
已 连接 的 网 络 接口 (意味 着 网 络 连 接 不 可 用 ) : 


public boolean isOnline() { 
ConnectivityManager connMgr = (ConnectivityManager ) 
getSystemService(Context.CONNECTIVITY SERVICE); 
NetworkInfo networkInfo - connMgr.getActiveNetworkInfo(); 
return (networkInfo !- null && networkInfo.isConnected()); 


我 们 可 以 使 用 Networklnfo.DetailedState， 来 获取 更 加 详细 的 网 络 信息 ， 但 很 少 有 这 样 的 必 
要 。 


管理 网 络 的 使 用 情况 


我 们 可 以 实现 一 个 偏好 设置 的 activity ， 使 用 户 能 直接 设置 程序 对 网 络 资源 的 使 用 情况 。 例 如 : 


e 可 以 允许 用 户 仅 在 连接 到 Wi-Fi 时 上 传 视频 。 
e 可 以 根据 诸如 网 络 可 用 ， 时 间 间 隔 等 条 件 来 选择 是 否 做 同步 的 操作 。 


写 一 个 支持 连接 网 络 和 管理 网 络 使 用 的 app，manifest 里 需要 有 正确 的 权限 和 intent filter 。 


e manifest 文件 里 包括 下 面 的 权限 : 


o android.permission.INTERNET 一 一 允许 应 用 程序 打开 网 络 套 接 字 。 





o android.permission.ACCESS NETWORK STATE 


o 


允许 应 用 程序 访问 网 络 连接 


信息 


。 我 们 可 以 为 ACTION. MANAGE. NETWORK. USAGE action (Android 4.0 中 引入 ) 声明 
intent filter， 表 示 我 们 的 应 用 定义 了 一 个 提供 控制 数据 使 用 情况 选项 的 
activity 。ACTION_MANAGE_NETWORK_USAGE 显示 管理 指定 应 用 程序 网 络 数据 使 用 
情况 的 设置 。 当 我 们 的 app 有 一 个 允许 用 户 控制 网 络 使 用 情况 的 设置 activity 时 ， 我 们 应 
该 为 activity 声明 这 个 intent filter。 在 章节 概览 提供 的 示例 应 用 中 ， 这 个 action 被 
SettingsActivity 类 处 理 ， 它 提供 了 偏好 设置 Ul 来 让 用 户 决 定 何 时 进行 下 载 。 


«?xml version="1.0" encoding="utf-8"?> 
«manifest xmlns:android-"http://schemas.android.com/apk/res/android" 


packagez"com.example.android.networkusage" 


ES 


«uses-sdk android:minSdkVersion="4" 
android: targetSdkVersion="14" /> 


<uses-permission android:name="android.permission. INTERNET" /> 
«uses-permission android:name-"android.permission.ACCESS NETWORK STATE" /> 


«application 
eee 


«activity android: label="SettingsActivity" android:name=".SettingsActivity"> 


<intent-filter> 
«action android:name="android.intent.action.MANAGE_NETWORK_USAGE" /> 


«category android:name-"android.intent.category.DEFAULT" /> 
</intent-filter> 
</activity> 
</application> 


</manifest> 


实现 一 个 首选 项 Activity 


正如 上 面 manifest 片段 中 看 到 的 那样 ， settingsActivity 有 一 个 
ACTION MANAGE NETWORK USAGE action 的 intent filter ^ settingsActivity 是 
PreferenceActivity 的 子 类 ， 它 展示 一 个 偏好 设置 页 面 (如 下 两 张 图 ) 让 用 户 指定 以 下 内 容 : 


。 是 否 显示 每 个 XML 提要 条 目的 总 结 ， 或 者 只 是 每 个 条 目的 一 个 链接 。 
e 是 否 在 网 络 连接 可 用 时 下 载 XML 提要 ， 或 者 仅仅 在 Wi-Fi FFR 


B SettingsActivity 


Download Feed 


Show Summaries 


show a nmary for each link 


Only when on Wi-Fi 


On any network 


Cancel 





Figure 1. 首选 项 activity 


下 面 是 settingsActivity 。 请 注意 它 实 现 了 OnSharedPreferenceChangeListener ° 4 M P 
改变 了 他 的 偏好 ， 就 会 触发 onSharedPreferenceChanged()， 这 个 方法 会 设置 
refreshDisplay 为 true (这 里 的 变量 存在 于 自己 定义 的 activity， 见 下 一 部 分 的 代码 示例 ) © 
这 会 使 得 当 用 户 返 回 到 main activity 的 时 候 进 行 刷新 : 


(请 注意 ， 代 码 中 的 注释 ， 不 得 不 说 ，Googler 写 的 Code 看 起 来 就 是 舒服 ) 


管理 网 络 的 使 用 情况 


public class SettingsActivity extends PreferenceActivity implements OnSharedPreference 
ChangeListener { 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


// Loads the XML preferences file 
addPreferencesFromResource(R.xml.preferences); 


@Override 
protected void onResume() { 
super .onResume(); 


// Registers a listener whenever a key changes 
getPreferenceScreen( ).getSharedPreferences().registerOnSharedPreferenceChangeL 
istener(this); 


} 


@Override 
protected void onPause() { 
super.onPause(); 


// Unregisters the listener set in onResume(). 

// It's best practice to unregister listeners when your app isn't using them to 
cut down on 

// unnecessary system overhead. You do this in onPause(). 

getPreferenceScreen().getSharedPreferences().unregisterOnSharedPreferenceChange 
Listener(this); 


} 


// When the user changes the preferences selection, 

// onSharedPreferenceChanged() restarts the main activity as a new 

// task. Sets the the refreshDisplay flag to "true" to indicate that 

// the main activity should update its display. 

// The main activity queries the PreferenceManager to get the latest settings. 


@Override 
public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String 


key) { 
// Sets refreshDisplay to true so that when the user returns to the main 
// activity, the display refreshes to reflect the new settings. 
NetworkActivity.refreshDisplay = true; 


响应 偏好 设置 的 改变 
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当 用 户 在 设置 界面 改变 了 偏好 ， 它 通常 都 会 对 app 的 行为 产生 影响 。 在 下 面 的 代码 示例 中 ， 
app 会 在 onstart() 方法 中 检查 偏好 设置 。 如 果 设 置 的 类 型 与 当前 设备 的 网 络 连 接 类 型 相 一 
致 ， 那 么 程序 就 会 下 载 数 据 并 刷新 显示 。 (例如 , 如 果 设 置 是 "Wi-Fi" 并 且 设 备 连 接 了 Wi- 


Fi) 


(这 是 一 个 很 好 的 代码 示例 ， 如 何 选 择 合适 的 网 络 类 型 进行 下 载 操作 ) 


public class NetworkActivity extends Activity { 


public static final String WIFI = "Wi-Fi"; 
public static final String ANY - "Any"; 
private static final String URL - "http://stackoverflow.com/feeds/tag?tagnames-and 


roid&sort-newest"; 


) ; 


// Whether there is a Wi-Fi connection. 

private static boolean wifiConnected - false; 
// Whether there is a mobile connection. 
private static boolean mobileConnected - false; 
// Whether the display should be refreshed. 
public static boolean refreshDisplay - true; 


// The user's current network preference setting. 
public static String sPref - null; 


// The BroadcastReceiver that tracks network connectivity changes. 
private NetworkReceiver receiver - new NetworkReceiver(); 


@Override 
public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


// Registers BroadcastReceiver to track network connection changes. 
IntentFilter filter - new IntentFilter(ConnectivityManager.CONNECTIVITY ACTION 


receiver - new NetworkReceiver(); 
this.registerReceiver(receiver, filter); 


QOverride 
public void onDestroy() { 
super.onDestroy(); 
// Unregisters BroadcastReceiver when app is destroyed. 
if (receiver !- null) { 
this.unregisterReceiver(receiver); 


// Refreshes the display if the network connection and the 
// pref settings allow it. 


@Override 
public void onStart () { 


super.onStart(); 


// Gets the user's network preference settings 
SharedPreferences sharedPrefs - PreferenceManager.getDefaultSharedPreferences( 


this); 
// Retrieves a string value for the preferences. The second parameter 
// is the default value to use if a preference value is not found. 
sPref = sharedPrefs.getString("listPref", "Wi-Fi"); 
updateConnectedFlags(); 
if(refreshDisplay) { 

loadPage(); 
} 
} 


// Checks the network connection and sets the wifiConnected and mobileConnected 
// variables accordingly. 
public void updateConnectedFlags() { 
ConnectivityManager connMgr = (ConnectivityManager) 
getSystemService(Context.CONNECTIVITY SERVICE); 


NetworkInfo activeInfo - connMgr.getActiveNetworkInfo(); 
if (activeInfo !- null && activeInfo.isConnected()) { 
wifiConnected - activeInfo.getType() -- ConnectivityManager.TYPE WIFI; 
mobileConnected - activeInfo.getType() -- ConnectivityManager.TYPE MOBILE; 
} else { 
wifiConnected = false; 
mobileConnected = false; 


// Uses AsyncTask subclass to download the XML feed from stackoverflow.com. 
public void loadPage() { 
if (((sPref.equals(ANY)) && (wifiConnected || mobileConnected) ) 
|| ((sPref.equals(WIFI)) && (wifiConnected))) ( 
// AsyncTask subclass 
new DownloadXmlTask().execute(URL); 
} else { 
showErrorPage(); 


检测 网 络 连 接 变 化 


最 后 一 部 分 是 关于 BroadcastReceiver 的 子 类 : NetworkReceiver 。 当 设 备 网 络 连 接 改 变 

时 > NetworkReceiver 会 监听 到 CONNECTIVITY ACTION ， 这 时 需要 判断 当前 网 络 连接 类 
型 并 相应 的 设置 好 wificonnected 与 mobileConnected 。 这 样 做 的 结果 是 下 次 用 户 回 到 app 
时 ， app 只 会 下 载 最 新 返回 的 结果 。 如 果 NetworkActivity.refreshDisplay 被 设置 为 true ? 
app 会 更 新 显示 。 

我 们 需要 控制 好 BroadcastReceiver 的 使 用 ， 不 必要 的 声明 注册 会 浪费 系统 资源 。 示 例 应 用 
在 onCreate() 中 注册 BroadcastReceiver NetworkReceiver ， 在 onDestroy() T 49 RE o 
这 样 做 会 比 在 manifest 里 面 声明 «receiver» 更 轻巧 。 当 我 们 在 manifest €. da 5 8] — 4 
«receiver» ， 我 们 的 程序 可 以 在 任何 时 候 被 唤醒 ， 即 使 我 们 已 经 好 几 个 星期 没有 运行 这 个 程 
序 了 。 而 通过 前 面 的 办 法 注册 NetworkReceiver ， 可 以 确保 用 户 离开 我 们 的 应 用 之 后 ， 应 用 不 
会 被 唤起 。 PRN 实 要 在 manifest 中 声明 <receiver> ， 且 确保 知道 何 时 需要 使 用 到 

它 ， 那 么 可 以 在 合适 的 地 方 使 用 setComponentEnabledSetting() 来 开启 或 者 关闭 它 


下 面 是 NetworkReceiver 的 代码 : 


public class NetworkReceiver extends BroadcastReceiver { 


@Override 
public void onReceive(Context context, Intent intent) { 


ConnectivityManager conn = (ConnectivityManager ) 
context.getSystemService(Context.CONNECTIVITY SERVICE); 
NetworkInfo networkInfo - conn.getActiveNetworkInfo(); 


// Checks the user prefs and the network connection. Based on the result, decides 


whether 


on. 


// to refresh the display or keep the current display. 


// If the userpref is Wi-Fi only, checks to see if the device has a Wi-Fi connecti 


if (WIFI.equals(sPref) && networkInfo !- null && networkInfo.getType() -- Connecti 
vityManager.TYPE WIFI) { 


// If device has its Wi-Fi connection, sets refreshDisplay 

// to true. This causes the display to be refreshed when the user 

// returns to the app. 

refreshDisplay - true; 

Toast.makeText(context, R.string.wifi connected, Toast.LENGTH SHORT).show(); 


// If the setting is ANY network and there is a network connection 


// (which by process of elimination would be mobile), sets refreshDisplay to true. 


) eise if (ANY.equals(sPref) && networkInfo !- null) ( 
refreshDisplay - true; 


// Otherwise, the app can't download content--either because there is no network 
// connection (mobile or Wi-Fi), or because the pref setting is WIFI, and there 
// is no Wi-Fi connection. 
// Sets refreshDisplay to false. 
} else { 

refreshDisplay = false; 

Toast .makeText(context, R.string.lost_connection, Toast.LENGTH SHORT).show(); 
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解析 XML 数据 


编写 :kesenhoo - /$ x-:http://developer.android.com/training/basics/network-ops/xml.html 


Extensible Markup Language (XML) 是 一 组 将 文档 编码 成 机 器 可 读 形 式 的 规则 ， 也 是 一 种 
在 网 络 上 共享 数据 的 普遍 格式 。 频 繁 更 新 内 容 的 网 站 ， 比 如 新 闻 网 站 或 者 博客 ， 经 常会 提供 
XML 提要 (XML feed) 来 使 得 外 部 程序 可 以 跟 上 内 容 的 变化 。 下 载 与 解析 XML 数据 是 网 络 
连接 相关 app 的 一 个 常见 功能 。 这 一 课 会 介绍 如 何 解 析 XML 文档 并 使 用 它们 的 数据 。 


示例 : NetworkUsage.zip 


选择 一 个 Parser 
我 们 推荐 XmlPullParser > È Æ Android 上 一 个 高 效 且 可 维护 的 解析 XML 的 方法 。 Android 
上 有 这 个 接口 的 两 种 实现 方式 : 


e KXmlParser， 通 过 XmlPullParserFactory.newPullParser() 得 到 。 
è ExpatPullParser ， 通 过 Xml.newPullParser() 得 到 。 


两 个 选择 都 是 比较 好 的 o。 下面 的 示例 中 是 通过 xml.newPullParser() 得 到 ExpatPullParser ° 


分 析 Feed 
解析 一 个 feed 的 第 一 步 是 决定 我 们 需要 获取 的 字段 。 这 样 解 析 器 便 去 抽取 出 那些 需要 的 字段 
而 忽视 其 他 的 字段 2. 


下 面 的 XML 片段 是 章节 概览 示例 app 中 解析 的 Feed 的 片段 。StackOverflow.com 上 每 一 个 
帖子 在 feed PU. AS ILPREN FRAN entry 标签 的 形式 出 现 。 


<?xml version="1.0" encoding="utf-8"?> 

«feed xmlns="http://www.w3.org/2005/Atom" xmlns:creativeCommons-"http://backend.userla 
nd.com/creativeCommonsRssModule" ..."» 

«title type="text">newest questions tagged android - Stack Overflow</title> 


«entry» 


«/entry» 
«entry» 
<id>http://stackover flow. com/q/9439999</id> 
«re:rank scheme="http://stackoverflow.com">0</re: rank> 
«title type-"text"»Where is my data file?</title> 
«category scheme-"http://stackoverflow.com/feeds/tag?tagnames-android&sort-new 
est/tags" term="android"/> 
«category scheme-"http://stackoverflow.com/feeds/tag?tagnames-android&sort-new 
est/tags" term="file"/> 
«author» 
«name»cliff2310«/name» 
<uri>http://stackoverflow.com/users/1128925</uri> 
</author> 
«link rel-"alternate" href="http://stackoverflow.com/questions/9439999/where-i 
s-my-data-file" /» 
<published>2012-02-25T00:30:54Z</published> 
<updated>2012-02-25T00:30:54Z</updated> 
«summary type="html"> 
<p>I have an Application that requires a data file...</p> 


</summary> 
</entry> 
<entry> 
</entry> 
</feed> 


示例 app A entry 标签 与 它 的 子 标签 title * link 和 summary 中 提取 数据 . 


实例 化 Parser 


下 一 步 就 是 实例 化 一 个 parser 并 开始 解析 的 操作 。 在 下 面 的 片段 中 ， 一 个 parser 被 初始 化 来 
处 理 名 称 空 间 ， 并 且 将 InputStream 作为 输入 。 它 通过 调用 nextTag() 开始 解析 ， 并 调用 
readFeed() 方法 ， readFeed() 方法 会 提取 并 处 理 app 需要 的 数据 : 


public class StackOverflowXmlParser { 
// We don't use namespaces 
private static final String ns - null; 


public List parse(InputStream in) throws XmlPullParserException, IOException { 

igi SE 
XmlPullParser parser - Xml.newPullParser(); 
parser.setFeature(XmlPullParser.FEATURE PROCESS NAMESPACES, false); 
parser.setInput(in, null); 
parser.nextTag(); 
return readFeed(parser); 

} finally ( 
in.close(); 


1% St Feed 


readFeed() 方法 实际 的 工作 是 处 理 feed 的 内 容 。 它 寻找 一 个 "entry" 的 标签 作为 递归 处 理 整 
个 feed 的 起 点 。 readFeed() 方法 会 跳 过 不 是 entry 的 标签 。 当 整个 feed 都 被 递归 处 理 
后 ， readFeed() 会 返回 一 个 从 feed 中 提取 的 包含 了 entry 标签 内 容 (包括 里 面 的 数据 成 
员 ) 的 List。 然 后 这 个 List 成 为 parser 的 返回 值 。 


private List readFeed(XmlPullParser parser) throws XmlPullParserException, IOException 


t 


List entries - new ArrayList(); 


parser.require(XmlPullParser.START TAG, ns, "feed"); 
while (parser.next() != XmlPullParser.END TAG) { 
if (parser.getEventType() !- XmlPullParser.START TAG) { 
continue; 
} 
String name = parser.getName(); 
// Starts by looking for the entry tag 
if (name.equals("entry")) { 
entries.add(readEntry(parser) ); 
} else { 
skip(parser); 


} 


return entries; 





解析 XML 


解析 XML feed 的 步骤 如 下 : 


1. 正如 在 上 面 分 析 Feed 所 说 的 ， 判 断 出 应 用 中 想 要 的 标签 。 这 个 例子 抽取 了 entry 标签 
与 它 的 内 部 标签 title ， link 和 summary 中 的 数据 。 

2. 创建 下 面 的 方法 : 

3. 为 每 一 个 我 们 想 要 获取 的 标签 创建 一 个 "read" 方法 。 例 如 readEntry() ， readTitle() 
等 等 。 解 析 器 从 输入 流 中 读 取 标签 。 当 读 取 到 entry ，title ， link 或 者 summary 
标签 时 ， 它 会 为 那些 标签 调用 相应 的 方法 。 否 则 ， 跳 过 这 个 标签 。 


4. 为 每 一 个 不 同 的 标签 创建 提取 数据 的 方法 ， 和 使 parser 继续 解析 下 一 个 标签 的 方法 。 例 
如 : 


o 对 于 title 和 summary 标签 ， 解析 器 调用 readText() ° 这 个 方法 通过 调用 
parser.getText() 来 获取 数据 。 


o 对 于 link 标签 ， 解 析 器 先 判断 这 个 link 是 否 是 我 们 想 要 的 类 型 。 然 后 再 使 用 
parser.getAttributeValue() 来 获取 link 标签 的 值 。 


o 对 于 entry 标签 ， 解 析 器 调用 readEntry() 。 这 个 方法 解析 entry 的 内 部 标签 并 返 
回 一 个 带 有 title ， link 和 summary 数据 成 员 的 Entry xt Ro 


5. 一 个 递归 的 辅助 方法 skipo 。 关 于 这 部 分 的 讨论 ， 请 看 下 面 一 部 分 内 容 ; 跳 过 不 关心 


的 标签 。 


下 面 的 代码 演示 了 如 何 解析 entries > titles > links 与 summaries ° 


public static class Entry { 
public final String title; 
public final String link; 
public final String summary; 


private Entry(String title, String summary, String link) { 
this.title - title; 
this.summary - summary; 
this.link - link; 


// Parses the contents of an entry. If it encounters a title, summary, or link tag, ha 
nds them off 
// to their respective "read" methods for processing. Otherwise, skips the tag. 
private Entry readEntry(XmlPullParser parser) throws XmlPullParserException, IOExcepti 
on { 

parser.require(XmlPullParser.START TAG, ns, "entry"); 

String title - null; 

String summary - null; 


String link = null; 
while (parser.next() != XmlPullParser.END TAG) { 
if (parser.getEventType() !- XmlPullParser.START TAG) ( 
continue; 
} 
String name = parser.getName(); 
if (name.equals("title")) { 
title = readTitle(parser); 
) else if (name.equals("summary")) { 
summary = readSummary(parser) ; 
) else if (name.equals("link")) { 
link - readLink(parser); 
} else { 
skip(parser); 


} 


return new Entry(title, summary, link); 


// Processes title tags in the feed. 
private String readTitle(XmlPullParser parser) throws IOException, XmlPullParserExcept 
ion { 

parser.require(XmlPullParser.START TAG, ns, "title"); 

String title - readText(parser); 

parser.require(XmlPullParser.END TAG, ns, "title"); 

return title; 


// Processes link tags in the feed. 
private String readLink(XmlPullParser parser) throws IOException, XmlPullParserExcepti 
on { 
String link = ""; 
parser.require(XmlPullParser.START TAG, ns, "link"); 
String tag - parser.getName(); 
String relType - parser.getAttributeValue(null, "rel"); 
if (tag.equals("link")) ( 
if (relType.equals("alternate")){ 
link - parser.getAttributeValue(null, "href"); 
parser.nextTag(); 


} 
parser.require(XmlPullParser.END TAG, ns, "link"); 


return link; 


// Processes summary tags in the feed. 
private String readSummary(XmlPullParser parser) throws IOException, XmlPullParserExce 
ption { 

parser.require(XmlPullParser.START TAG, ns, "summary"); 

String summary - readText(parser); 

parser.require(XmlPullParser.END TAG, ns, "summary"); 

return summary; 


// For the tags title and summary, extracts their text values. 
private String readText(XmlPullParser parser) throws IOException, XmlPullParserExcepti 
on { 
String result - 
if (parser.next() == XmlPullParser.TEXT) { 
result - parser.getText(); 


nn, 
了 


parser.nextTag(); 


} 


return result; 


w 


跳 过 不 关心 的 标签 


上 面 描述 的 XML 解析 步骤 中 有 一 步 就 是 跳 过 不 关心 的 标签 ， 下 面 演示 解析 器 的 skipo 方 
法 : 


private void skip(XmlPullParser parser) throws XmlPullParserException, IOException { 
if (parser.getEventType() !- XmlPullParser.START TAG) { 
throw new IllegalStateException(); 
} 
int depth = 1; 
while (depth != 0) { 
switch (parser.next()) { 
case XmlPullParser.END TAG: 
depth--; 
break; 
case XmlPullParser.START TAG: 
depth++; 
break; 


下 面 解释 这 个 方法 如 何 工作 : 


e 如 果 当 前 事件 不 是 一 个 START TAG ， 抛 出 异常 。 
e 它 消 耗 掉 START_TAG 以 及 接 下 来 的 所 有 内 容 ， 包 括 与 开始 标签 配对 的 END_TAG ° 
e 为 了 保证 方法 在 遇 到 正确 的 END TAG 时 停止 ， 而 不 是 在 最 开始 的 START_TAG 后 面 的 第 
一 个 标签 ， 方 法 随时 记录 髓 套 深度 。 
因此 如 果 目 前 的 标签 有 子 标签 , 那么 直到 解析 器 已 经 处 理 了 所 有 位 于 START_TA6 与 对 应 的 
END TAG 之 间 的 事件 之 前 ， depth 的 值 不 会 为 0。 例 如， 看 解析 器 如 何 跳 过 <author> 标 
签 ， 它 有 2 个 子 标 签 ， <name> 5 <uri> 


e 第 一 次 循环 , 在 «author» 之 后 parser 遇 到 的 第 一 个 标签 是 <name> 标签 的 
START TAG ° depth 值 变 为 2。 

e 第 二 次 循环 , parser 遇 到 的 下 一 个 标签 是 END_TA6 «/name» ° depth 值 变 为 1。 

e 第 三 次 循环 , parser 遇 到 的 下 一 个 标签 是 START_ TAG «uri» ° depth 值 变 为 2。 

e 第 四 次 循环 , parser 遇 到 的 下 一 个 标签 是 END TAG </uri> ° depth 值 变 为 1。 

e 第 五 次 同时 也 是 最 后 一 次 循环 , parser 遇 到 的 下 一 个 标签 是 END TAG </author> ° 
depth 值 变 为 0。 表 明成 功 跳 过 了 <author> 标签 。 


使 用 XML 数据 


示例 程序 是 在 AsyncTask 中 获取 与 解析 XML 数据 的 。 这 会 在 主 UI 线程 之 外 进行 处 理 。 当 处 
理 完毕 后 ，app 会 更 新 main activity ( NetworkActivity ) 的 Ul 


在 下 面 示例 代码 中 ， loadPage() 方法 做 了 下 面 的 事情 : 


。 初始 化 一 个 带 有 URL 地 址 的 字符 串 变 量 ， 用 来 订阅 XML feed 。 

° 如 果 用 户 设 置 与 网 络 连接 都 允许 ， 会 调用 new DownloadXmlTask().execute(url) ° 这 会 初 
始 化 一 个 新 的 DownloadxmlTask 对 象 《AsyncTask 的 子 类 ) 并 且 开 始 执行 它 的 execute() 
方法 ， 这 个 方法 会 下 载 并 解析 feed， 并 返回 展示 在 UI 上 的 字符 串 。 


public class NetworkActivity extends Activity { 

public static final String WIFI - "Wi-Fi"; 

public static final String ANY - "Any"; 

private static final String URL - "http://stackoverflow.com/feeds/tag?tagnames-and 
roid&sort-newest"; 


// Whether there is a Wi-Fi connection. 

private static boolean wifiConnected - false; 
// Whether there is a mobile connection. 
private static boolean mobileConnected - false; 
// Whether the display should be refreshed. 
public static boolean refreshDisplay - true; 
public static String sPref - null; 


// Uses AsyncTask to download the XML feed from stackoverflow.com. 
public void loadPage() { 


if((sPref.equals(ANY)) && (wifiConnected || mobileConnected)) ( 
new DownloadXmlTask().execute(URL); 


} 
else if ((sPref.equals(WIFI)) && (wifiConnected)) { 


new DownloadXmlTask().execute(URL); 
} else { 
// show error 


下 面 展示 的 是 AsyncTask 的 子 类 > pownloadxmlTask ， 实 现 了 AsyncTask 的 如 下 方法 : 


e dolnBackground() 执行 loadxmlFromNetwork() 方法 。 它 以 feed 的 URL 作为 参 
数 。 loadxmlFromNetwork() 获取 并 处 理 feed。 当 它 完成 时 ， 返 回 一 个 结果 字符 串 。 
e onPostExecute() 接收 返回 的 字符 串 并 将 其 展示 在 UI 上 。 





// Implementation of AsyncTask used to download XML feed from stackoverflow.com. 
private class DownloadXmlTask extends AsyncTask«String, Void, String» { 
@Override 
protected String doInBackground(String... urls) { 
try { 
return loadXmlFromNetwork(urls[0]); 
) catch (IOException e) { 
return getResources().getString(R.string.connection error); 
) catch (XmlPullParserException e) { 
return getResources().getString(R.string.xml error); 


@Override 

protected void onPostExecute(String result) { 
setContentView(R. layout .main) 
// Displays the HTML string in the UI via a WebView 
WebView myWebView = (WebView) findViewById(R.id.webview) ; 
myWebView.loadData(result, "text/html", null); 


下 面 是 DownloadxmlTask 中 调用 的 1oadxmlFromNetwork() 方法 做 的 事情 : 


1. 实例 化 一 个 stackoverflowxmlParser 。 它 同样 创建 一 个 Entry WK ( entries ) 的 
List， 和 title ， url ， summary ， 来 保存 从 XML feed 中 提取 的 值 。 

2. 调用 downloadurl() ， 它 会 获取 feed, 并 将 其 作为 InputStream 返回 。 

3. 使 用 stackoverflowxmlParser 解析 InputStream ° stackoverflowxmlParser 用 从 feed 中 
获取 的 数据 填充 entries 的 List。 

4. 处 理 entries 的 List， 并 将 feed 数据 与 HTML 标记 结合 起 来 。 

5. 返回 一 个 HTML 字符 串 ，AsyncTask 的 onPostExecute() 方法 会 将 其 展示 在 main 
activity 4) Ul 上 。 


// Uploads XML from stackoverflow.com, parses it, and combines it with 
// HTML markup. Returns HTML string. [iX E T nÁ HB EX Download] 
private String loadXmlFromNetwork(String urlString) throws XmlPullParserException, IOE 
xception { 
InputStream stream = null; 
// Instantiate the parser 
StackOverflowXmlParser stackOverflowXmlParser = new StackOverflowXmlParser(); 
List«Entry» entries - null; 
String title - null; 
String url - null; 
String summary - null; 
Calendar rightNow - Calendar.getInstance(); 
DateFormat formatter = new SimpleDateFormat("MMM dd h:mmaa"); 


// Checks whether the user set the preference to include summary text 
SharedPreferences sharedPrefs = PreferenceManager .getDefaultSharedPreferences(this 


) ; 


) ; 


boolean pref = sharedPrefs.getBoolean("summaryPref", false); 


StringBuilder htmlString - new StringBuilder(); 
htmlString.append("<h3>" + getResources().getString(R.string.page title) + "</h3>" 


htmlstring.append("<em>" + getResources().getString(R.string.updated) + " " + 
formatter. format(rightNow.getTime()) + "</em>"); 


try { 
stream = downloadUrl(urlString); 


entries = stackOverflowXmlParser.parse(stream); 
// Makes sure that the InputStream is closed after the app is 
// finished using it. 
} finally { 
if (stream != null) { 
stream.close(); 


// StackOverflowXmlParser returns a List (called "entries") of Entry objects. 
// Each Entry object represents a single post in the XML feed. 
// This section processes the entries list to combine each entry with HTML markup. 
// Each entry is displayed in the UI as a link that optionally includes 
// a text summary. 
for (Entry entry : entries) { 

htmlString.append("<p><a href='"); 

htmlString.append(entry.link); 

htmlString.append("'»" + entry.title + "</a></p>"); 

// If the user set the preference to include summary text, 

// adds it to the display. 

if (pref) { 

htmlString.append(entry.summary); 


} 
return htmlstring.toString(); 


// Given a string representation of a URL, sets up a connection and gets 


// an input stream. 
【关于 Timeout 具 体 应 该 设置 多 少 ， 可 以 借鉴 这 里 的 数据 ， 当 然 前 提 是 一 般 情 况 下 ]】 
// Given a string representation of a URL, sets up a connection and gets 


// an input stream. 


private InputStream downloadUrl(String urlString) throws IOException { 


URL url - new URL(urlString); 

HttpURLConnection conn - (HttpURLConnection) url.openConnection(); 
conn.setReadTimeout(10000 /* milliseconds */); 
conn.setConnectTimeout(15000 /* milliseconds */); 
conn.setRequestMethod("GET"); 

conn.setDoInput(true); 

// Starts the query 

conn.connect(); 

return conn.getInputStream(); 


解析 XML 数据 


341 


传输 数据 时 避 狗 消耗 大 量 电量 


编写 :kesenhoo - 原文 :http://developer.android.com/training/efficient- 


downloads/index.html 
在 这 一 章 ， 我 们 将 学 习 最 小 化 下 载 ， 网 络 连接 ， 尤 其 是 无 线 电 连接 对 电量 的 影响 。 


下 面 几 节 课 会 演示 如 何 使 用 像 缓 存 〈caching) ^ 4639 (polling) 和 预 取 (prefetching) 这 样 
的 技术 来 调度 与 执行 下 载 操 作 。 我 们 还 会 学 习 无 线 电波 的 power-use 属性 配置 是 如 何 影响 我 
们 对 于 在 何 时 ， 用 什么 ， 以 何 种 方式 来 传输 数据 的 选择 。 当 然 这 些 选择 是 为 了 最 小 化 对 电量 
的 影响 。 


我 们 同样 需要 阅读 优化 电池 使 用 时 间 


Lesson 


优化 下 载 以 高 效 地 访问 网 络 


这 节 课 介绍 了 无 线 电波 状态 机 (wireless radio state machine) ， 解 释 了 app 的 连接 模型 
(connectivity model) 如 何 与 它 交互 ， 以 及 如 何 最 小 化 数据 连接 和 使 用 预 取 (prefetching) 
和 捆绑 (bundling) 来 最 小 化 数据 传输 对 电池 消耗 的 影响 。 


最 小 化 定期 更 新 造成 的 影响 


这 节 课 我 们 将 了 解 如 何 调整 刷新 频率 以 最 大 程度 减轻 底层 无 线 电波 状态 机 的 后 台 更 新 所 造成 
的 影响 。 


重复 的 下 载 是 宛 余 的 
减少 下 载 的 最 根本 途径 是 只 下 载 我 们 需要 的 内 容 。 这 节 课 介绍 了 消除 宛 余下 载 的 一 些 最 佳 实 
R o 

e 根据 网 络 连接 类 型 来 调整 下 载 模式 


不 同 连接 类 型 对 电池 电量 的 影响 并 不 相同 。 不 仅仅 是 Wi-Fi 比 无 线 电波 更 省 电 ， 不 同 的 无 
线 电波 技术 对 电量 也 有 不 同 的 影响 。 


优化 下 载 以 高 效 地 访问 网 络 


编写 :kesenhoo - /$ X :http://developer.android.com/training/efficient-downloads/efficient- 
network-access.html 


使 用 无 线 电 波 (wireless radio) 进行 传输 数据 很 可 能 是 我 们 app 最 耗 电 的 来 源 之 一 。 为 了 最 
小 化 网 络 连接 对 电量 的 消耗 ， 懂 得 连接 模式 〈connectivity model) 会 如 何 影响 底层 的 无 线 电 
硬件 设备 是 至 关 重 要 的 。 


这 节 课 介绍 了 无 线 电波 状态 机 (wireless radio state machine) ， 并 解释 了 app 的 连接 模式 是 
如 何 与 状态 机 进行 交互 的 。 然 后 会 提出 建议 的 方法 来 最 小 化 我 们 的 数据 连接 ， 使 用 预 取 

(prefetching) 与 捆绑 (bundle) 的 方式 进行 数据 的 传输 ， 这 些 操作 都 是 为 了 最 小 化 电量 的 
消耗 。 


无 线 电波 状态 机 


一 个 处 于 完全 工作 状态 的 无 线 电 会 大 量 消耗 电量 ， 因 此 需要 学 习 如 何在 不 同 能 量 状态 下 进行 
过 渡 ， 当 无 线 电 没有 工作 时 ， 节 省 电量 ， 当 需要 时 尝试 最 小 化 与 无 线 电 波 供电 有 关 的 延迟 。 
典型 的 3G 无 线 电网 络 有 三 种 能 量 状态 : 

1. Full power : 当 无 线 连接 被 激活 的 时 候 ， 允 许 设备 以 最 大 的 传输 速率 进行 操作 。 

2. Low power : 一 种 中 间 状 态 ， 对 电量 的 消耗 差不多 是 Full power KA F 450% © 

3. Standby: 最 小 的 能 量 状态 ， 没 有 被 激活 或 者 需求 的 网 络 连接 。 
在 低 功 耗 和 空闲 的 状态 下 ， 电 量 消耗 会 显著 减少 。 这 里 也 会 介绍 重要 的 网 络 请 求 延迟 。 从 low 
power 能 量 状态 返回 到 full power 大 概 需 要 花费 1.5 秒 ， 从 空闲 能 量 状态 返回 到 full power 状 
态 需 要 花费 2 秒 。 
为 了 最 小 化 延迟 ， 状 态 机 使 用 了 一 种 后 滞 过 渡 到 更 低能 量 状态 的 机 制 。 下 图 是 一 个 典型 的 3G 
无 线 电波 状态 机 的 图 示 (AT&T 电 信 的 一 种 制式 ) 。 
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Figure 1. 典型 的 3G 无 线 电 状态 机 


在 每 一 台 设 备 上 的 无 线 状 态 机 ， 特 别 是 相关 的 传输 延迟 (“ 拖 尾 时 间 ”) 和 局 动 延迟 ， 都 会 根据 
无 线 电波 的 制式 (2G、3G、LTE 等 ) 不 同 而 改变 ， 并 且 由 设备 正在 所 使 用 的 网 络 进 行 定 义 与 
配置 。 


这 一 课 描述 了 一 种 典型 的 3G 无 线 电波 状态 机 ， 数 据 来 源 于 AT&T。 无 论 如 何 ， 这 些 原理 和 最 
佳 实践 结果 是 具有 通用 性 的 ， 在 其 他 的 无 线 电波 上 同样 适用 。 


这 种 方法 在 典型 的 网 页 浏览 操作 上 是 特别 有 效 的 ， 因 为 它 可 以 阻止 用 户 在 浏览 网 页 时 的 一 些 
不 受 欢迎 的 延迟 。 相 对 较 短 的 拖 尾 时 间 也 保证 了 当 一 个 网 页 浏览 会 话 结束 的 时 候 ， 无 线 电波 
可 以 转移 到 相对 较 低 的 能 量 状态 。 


不 幸 的 是 ， 这 个 方法 会 导致 在 现代 的 智能 机 系统 例如 Android 上 的 app 效率 低下 。 因 为 
Android 上 的 app 不 仅仅 可 以 在 前 台 运 行 (重点 关注 延迟 ) ， 也 可 以 在 后 台 运 行 (优先 处 理 
HUE) 。( 无 线 电波 的 状态 改变 会 影响 到 本 来 的 设计 ， 有 些 想 在 前 台 运 行 的 可 能 会 因为 切换 
到 低能 量 状态 而 影响 程序 效率 。 坊 问 说 手机 在 电量 低 的 状态 下 无 线 电波 的 强度 会 增 大 好 几 倍 
来 保证 信号 ， 可 能 与 这 个 有 关 。) 


App 如 何 影响 无 线 电波 状态 机 


每 次 创建 一 个 新 的 网 络 连接 ， 无 线 电波 就 切换 到 full power 状态 。 在 上 面 典型 的 3G 无 线 电波 
状态 机 情况 下 ， 无 线 电波 会 在 传输 数据 时 保持 在 full power 的 状态 〈 加 上 一 个 附加 的 5 秒 拖 尾 
HH) ， 再 之 后 会 经 过 12 秒 的 low power 能 量 状态 。 因 此 对 于 典型 的 3G 设备 ， 每 一 次 数据 
传输 的 会 话 都 会 导致 无 线 电波 消耗 大 概 20 秒 时 间 来 提取 电能 。 


实际 上 ， 这 意味 着 一 个 每 18 秒 传输 1 秒 非 捆绑 数据 (unbundled data) 的 app， 会 一 直 保 持 激 


IRA (18 = 1 秒 的 传输 数据 + 5 秒 过 渡 时 间 回 到 low power + 12 秒 过 渡 时 间 回 到 
standby) 。 因 此 ， 每 分 钟 会 消耗 18 秒 high power 的 电量 ，42 秒 low power 的 电量 。 


通过 比较 ， 同 一 个 app， 每 分 钟 传输 持续 3 秒 的 捆绑 数据 (bundle data) ， 会 使 得 无 线 电 波 持 
续 在 high power 状态 仅仅 8 秒 ， 在 low power 状态 仅仅 12 秒 钟 。 


上 面 第 二 种 传输 捆绑 数据 (bundle data) 的 例子 ， 可 以 看 到 减少 了 大 量 的 电量 消耗 。 图 示 如 
Ta 
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Figure 2. 无 线 电 波 使 用 捆绑 数据 vs 无 线 电 波 使 用 非 捆 绑 数 据 


预 取 数据 


预 取 数据 是 一 种 减少 独立 数据 传输 会 话 数量 的 有 效 方法 。 预 取 技术 指 的 是 在 一 定时 间 内 ， 单 
次 连接 操作 ， 以 最 大 的 下 载 能 力 来 下 载 所 有 用 户 可 能 需要 的 数据 。 


通过 前 面 的 传输 数据 的 技术 ， 减 少 了 大 量 下 载 数据 所 需 的 无 线 电 波 激活 时 间 。 这 样 不 仅 节省 
了 电量 ， 也 改善 了 延迟 ， 降 低 了 带宽 ， 减 少 了 下 载 时 间 。 


预 取 技术 通过 减少 应 用 里 由 于 在 执行 一 个 动作 或 者 查看 数据 之 前 等 待 下 载 完 成 造成 的 延迟 ， 
来 提高 用 户 体验 。 


然而 ， 过 于 频繁 地 使 用 预 取 技术 ， 不 仅仅 会 导致 电量 消耗 快速 增长 ， 还 有 可 能 预 取 到 一 些 并 
不 需要 的 数据 ， 导 致 增加 带宽 的 使 用 和 下 载 配额 。 另 外 ， 需 要 确保 预 取 不 会 因为 app FH 
取 全 部 完成 而 延迟 应 用 的 启动 。 从 实践 的 角度 ， 那 意味 着 需要 逐步 处 理 数据 ， 或 者 按照 优先 
级 顺序 开始 进行 持续 的 数据 传递 ， 这 样 会 首先 下 载 和 处 理应 用 启动 时 需要 的 数据 。 

根据 正在 下 载 的 数据 大 小 与 可 能 被 用 到 的 数据 量 来 决定 预 取 的 频率 。 作 一 个 粗略 的 估计 ， 根 
据 上 面 介 绍 的 状态 机 ， 对 于 有 50% 的 机 会 被 当前 的 用 户 会 话 用 到 的 数据 ， 我 们 可 以 预 取 大 约 6 
秒 (大 约 1-2Mb)， 这 大 概 使 得 潜在 可 能 要 用 的 数据 量 与 可 能 已 经 下 载 好 的 数据 量 相 一 致 。 
通常 来 说 ， 预 取 1-5Mb 会 比较 好 ， 这 种 情况 下 ， 我 们 仅仅 只 需要 每 陋 2-5 分 钟 开始 另 一 段 下 
载 。 

根据 这 个 原理 ， 大 数据 的 下 载 ， 比 如 视频 文件 ， 应 该 每 隔 2-5 分 钟 开 始 另 一 段 下 载 ， 这 样 能 有 
效 的 预 取 到 下 面 几 分 钟 内 的 数据 进行 预览 。 

值得 注意 的 是 ， 更 进一步 的 下 载 应 该 是 是 捆绑 的 (bundled) ， 下 一 小 节 将 会 讲 到 ， 批 量 处 理 
传送 和 和 连接， 而 且 上 面 那些 大 概 的 数据 与 时 间 可 能 会 根据 网 络 连接 的 类 型 与 速度 有 所 变化 ， 
这 将 在 根据 网 络 连接 类 型 来 调整 下 载 模式 讲 到 。 
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让 我 们 来 看 一 些 例子 
一 个 音乐 播放 器 


我 们 可 以 选择 预 取 整个 专辑 ， 然 而 这 样 在 第 一 首 歌 曲 之 后 用 户 会 停止 听 歌 ， 那 么 就 浪费 了 大 
量 的 带宽 和 电量 。 


一 个 比较 好 的 方法 是 维护 正在 播放 的 那 首 歌曲 的 缓冲 区 。 对 于 流 媒 体 音 乐 ， 不 应 该 去 维护 一 
段 连 续 的 数据 流 ， 因 为 这 样 会 使 得 无 线 电 波 一 直 保 持 激 活 状 态 ， 而 应 该 考虑 用 HTTP. 流 直播 
来 集中 传输 音频 流 ， 就 像 上 面 描述 的 预 取 技术 一 样 〈 下 载 好 2Mb， 然 后 开始 一 次 取出 ， 再 去 
下 载 下 面 的 2Mb) 。 


一 个 新 闻 阅 读 器 


Le ds 完整 的 文章 仅 在 用 户 想 要 读 取 的 时 候 再 
去 读 取 ， 而 且 文章 也 会 因为 太 长 而 刚 开始 只 显示 部 分 信息 ， 等 用 户 下 滑 时 再 去 读 取 完整 信 
自 、 o 


A 


使 用 这 个 方法 ， 无 线 电 波 仅仅 会 在 用 户 点 击 更 多 信息 的 时 候 才 会 被 激活 。 但 是 ， 在 切换 文章 
分 类 预 阅读 文章 的 时 候 仍然 会 造成 大 量 潜在 的 消耗 。 


一 个 比较 好 的 方法 是 在 启动 的 时 候 预 取 一 个 合理 数量 的 数据 ， 比 如 在 启动 的 时 候 预 取 第 一 条 
新 闻 的 标题 与 缩 略图 信息 ， 确 保 较 短 的 启动 时 间 。 之 后 继续 获取 剩余 新 闻 的 标题 和 缩 略图 信 
息 。 同 时 获取 至 少 在 主要 标题 列表 中 可 用 的 每 篇 文章 的 文本 。 


E s i re a 
的 后 侣 程序 进行 逐一 获取 。 这 样 做 的 风险 是 花费 了 大 量 的 带宽 与 电量 去 下 载 一 些 不 会 阅读 到 
ae 文 种 方法 。 


其 中 的 一 个 解决 方案 是 ， 仅 当 在 连接 至 Wi-Fi 或 者 设备 正在 充电 时 ， 调 度 到 Full power 状态 进 
行 下 载 。 关 于 这 个 细节 的 实现 ， 我 们 将 在 后 面 的 根据 网 络 连接 类 型 来 调整 下 载 模 式 课程 中 介 


H e 


批量 处 理 传 送 和 连接 


BERRA PER “ 论 相关 传送 数据 的 大 小 一 一 当 使 用 典型 的 3G 无 线 网 络 时 ， 可 能 会 导 
致 无 线 电 波 消耗 大 约 20 秒 的 电量 。 








一 个 app 每 20 秒 ping 一 次 服务 器 ， 仅 仅 是 为 了 确认 app 正在 运行 和 对 用 户 可 见 ， 那 么 无 线 
电波 会 无 限期 地 处 于 开启 状态 ， 导 致 即 使 在 没有 实际 数据 传输 的 情况 下 ， 仍 会 消耗 大 量 电 


号 - 
o 


*X 
因此 ， 对 传送 的 数据 进行 捆绑 操作 和 创建 一 个 等 待 传输 队列 就 显得 非常 重要 。 操 作 正 确 的 


话 ， 可 以 使 得 大 量 的 数据 集中 进行 发 送 ， 这 样 使 得 无 线 电 波 的 激活 时 间 尽 可 能 的 少 ， 同 时 减 
少 大 部 分 电量 的 花费 。 


这 样 做 的 潜在 好 处 是 尽 可 能 在 每 次 传输 数据 的 会 话 中 尽 可 能 多 的 传输 数据 而 且 减 少 了 会 话 的 
次 数 。 


那 就 意味 着 我 们 应 该 通过 队列 延迟 容忍 传送 来 批量 处 理 我 们 的 传输 数据 ， 和 抢占 调度 更 新 和 
预 取 ， 使 得 当 要 求 时 间 敏 感 传输 时 ， 数 据 会 被 全 部 执行 。 同 样 地 ， 我 们 的 计划 更 新 和 定期 的 
预 取 应 该 开启 等 待 传输 队列 的 执行 工作 。 


预 取 数据 部 分 有 一 个 实际 的 例子 。 


以 上 述 使 用 定期 预 取 的 新 闻 应 用 为 例 。 新 闻 a 分 析 用 户 的 信息 来 了 解 用 户 的 阅读 模 
式 ， 并 按照 新 闻 报 道 的 受 欢迎 程度 对 新 闻 进 行 排序 。 为 了 保证 新 闻 最 新 ， 应 用 每 个 小 时 会 检 
查 更 新 一 次 。 为 了 节省 带宽 ， 预 取 缩 略图 信息 和 当 用 户 选 择 某 个 新 闻 时 下 载 全 部 图 片 ， 而 不 
去 下 载 每 篇 文章 的 所 有 图 片 。 

在 这 个 例子 中 ， 所 有 在 app 中 收集 到 的 分 析 信息 应 该 捆绑 在 一 起 并 放 入 下 载 队 列 ， 而 不 是 一 


收集 到 信息 就 传输 。 当 下 载 完 一 张 全 尺寸 的 图 片 或 者 执行 每 小 时 一 次 更 新 时 ， 应 该 传输 捆绑 
好 的 数据 。 





任何 时 间 敏 感 或 者 按 需 的 传输 一 一 例如 下 载 应 该 抢占 定期 更 新 。 计 划 好 的 更 
该 与 按 需 传送 在 同一 时 间 执 行 。 coe 小 了 执行 一 个 定期 更 新 的 开销 ， 该 定期 更 新 
过 下 载 必要 的 时 间 敏 感 图 片 的 背负 式 传输 实现 。 





减少 连 援 


常 来 说 ， 重 用 已 经 存在 的 网 络 连接 比 起 重新 建立 一 个 新 的 连接 更 有 效率 。 重 用 网 络 连接 同 
MF 导 在 拥挤 不 堪 的 网 络 环境 中 进行 更 加 智能 地 作出 反应 。 


当 可 以 捆绑 所 有 请 求 在 一 个 GET 里 面 的 时 候 ， 不 要 同时 创建 多 个 网 络 连接 或 者 把 多 个 GET 
请 求 进 行 串 联 。 


例如 ， 可 以 一 起 请 求 所 有 文章 的 情况 下 ， 不 要 根据 多 个 新 闻 会 话 进行 多 次 请 求 。 为 传输 与 服 
务 端 和 客户 端 timeout 相关 的 终止 / 终止 确认 数据 包 ， 无 线 电波 会 保持 激活 状态 ， 所 以 如 果 不 
需要 使 用 连接 时 ， 请 立即 关闭 ， 而 不 是 等 待 他 们 timeout 。 


之 前 说 道 ， 如 果 过 早 对 一 个 连接 执行 关闭 操作 ， 会 导致 需要 额外 的 开销 来 建立 一 个 新 的 连 
接 。 一 个 有 用 的 妥协 是 不 要 立即 关闭 连接 ， 而 是 在 国定 期 间 的 timeout 之 前 关闭 ( 即 稍微 晚点 
却 又 不 至 于 到 timeout) 。 


使 用 DDMS Network Traffic Tool 来 确定 问题 的 区 
域 


Android DDMS (Dalvik Debug Monitor Server) 包含 了 一 个 查看 网 络 使 用 详情 的 栏目 来 允许 跟 
踪 app 的 网 络 请 求 。 使 用 这 个 工具 ， 可 以 监测 app 是 在 何 时 ， 如 何 传输 数据 的 ， 从 而 进行 代 
码 的 优化 。 


Figure 3 显示 了 传输 少量 数据 的 网 络 模 型 ， 可 以 看 到 每 次 差不多 相隔 15 秒 ， 这 意味 着 可 以 通 
过 预 取 技 术 或 者 批量 上 传 来 大 幅 提 高 效率 。 
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Figure 3. 使 用 DDMS 检测 网 络 使 用 情况 


通过 监测 数据 传输 的 频率 与 每 次 传输 的 数据 量 ， 可 以 查看 出 哪些 位 置 应 该 进行 优化 。 通 常 
的 ， 我 们 会 寻找 类 似 短 穗 状 的 地 方 ， 这 些 位 置 可 以 延迟 ， 或 者 应 该 导致 一 个 后 来 的 传输 被 抢 
bo 


为 了 更 好 的 检测 出 问题 所 在 ，Traffic Status API 允许 我 们 使 用 
TrafficStats.setThreadStatsTag() 方法 标记 数据 传输 发 生 在 某 个 Thread 里 面 ， 然 后 可 以 手动 
地 使 用 tagsocket() 进行 标记 或 者 使 用 untagSocket() 来 取消 标记 ， 例 如 : 


TrafficStats.setThreadStatsTag(0xF00D); 
TrafficStats.tagSocket(outputSocket); 
// Transfer data using socket 
TrafficStats.untagSocket(outputSocket); 


Apache 的 HttpClient 与 URLConnection 库 可 以 根据 当前 的 getThreadStatusTag () 值 自动 
给 sockets 加 上 标记 。 那 些 库 在 通过 keep-alive pools 循环 的 时 候 也 会 为 sockets 加 上 或 者 取 
消 标签 。 


TrafficStats.setThreadStatsTag(0xF00D); 
try 1 

// Make network request using HttpClient.execute() 
} finally ( 

TrafficStats.clearThreadStatsTag(); 


} 


给 Socket 加 上 标签 (Socket tagging) 是 在 Android 4.0 上 才 被 支持 的 , 但 是 实际 情况 是 仅仅 
会 在 运行 Android 4.0.3 或 者 更 高 版 本 的 设备 上 才 会 显示 。 
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最 小 化 定期 更 新 造成 的 影响 


编写 :kesenhoo - 原文 :http://developer.android.com/training/efficient- 
downloads/regular updates.html 


最 佳 的 定期 更 新 频率 是 不 确定 的 ， 通 常 由 设备 状态 ， 网 络 连接 状态 ， 用 户 行 为 与 用 户 显 式 定 
义 的 偏好 而 决定 。 


Optimizing Battery Life 这 一 章 有 讨论 如 何 根据 主 设 备 状态 来 修改 更 新 频率 ， 从 而 达到 编写 一 
个 低 电 量 消耗 的 程序 。 可 执行 的 操作 包括 当 断 开 网 络 连接 的 时 候 去 关闭 后 台 服 务 ， 在 电量 比 
较 低 的 时 候 减 少 更 新 的 频率 等 。 


一 课 会 介绍 更 新 频率 是 多 少 才 会 使 得 更 新 操作 对 无 线 电 状态 机 的 影响 最 小 。(C2DM 与 指数 
退 避 算 法 的 使 用 ) 


使 用 Google Cloud Messaging 来 轮 询 


每 次 app 去 向 server 询问 权 dés 否 有 更 新 操作 的 时 候 ， 都 会 激活 无 线 电 ， 这 样 造成 了 不 必要 
的 能 量 消耗 (在 3G' HIF , 差不多 消耗 20 秒 的 能 量 ) S 


Google Cloud Messaging for Android (GCM) 是 一 个 用 来 从 server 到 特定 app — : 轻 


量 级 的 机 制 。 使 用 GCM，server 会 在 茶 个 app 需要 获取 新 数据 的 时 候 通 知 app 有 这 
自 、 o 


A 


比 起 轮 询 方式 (app 为 了 即时 拿 到 最 新 的 数据 需要 定时 去 ping server) > GCM 这 种 由 事件 驱 
动 的 模式 会 在 仅仅 有 数据 更 新 的 时 候 通 知 app 去 创建 网 络 连接 来 获取 数据 〈 很 显然 这 样 减 少 
了 app 的 大 量 操作 ， 当 然 也 减少 了 很 多 电量 消耗 ) 。 


GCM 需要 通过 使 用 持续 的 TCP/IP 连接 来 实现 操作 。 当 我 们 可 以 实现 自己 的 推送 服务 ， 最 好 
使 用 GCM (这 个 地 方 应 该 不 是 传统 意义 上 的 国定 IP， 可 以 理解 为 某 个 会 话 情况 下 ) 。 很 明 
显 ， 使 用 GCM 既 减 少 了 网 络 连接 次 数 ， 也 优化 了 带宽 ， 还 减少 了 对 电量 的 消耗 。 


PS : 大 陆 的 Google 框架 通常 被 移 除 掉 ， 这 导致 GCM 实际 上 根本 没有 办 法 在 大 陆 的 App 上 
使 用 。 


使 用 不 严格 的 重复 通知 和 指数 避 退 算法 来 优化 轮 询 


如 果 需 要 使 用 轮 询 机 制 ， 在 不 影响 用 户 体 验 的 前 提 下 ， 设 置 默认 的 更 新 频率 当然 是 越 低 越 好 
(减少 耗 电量 ) 。 


一 个 简单 的 方法 是 给 用 户 显 式 修改 更 新 频率 的 选项 ， 人 允许 用 户 自 己 来 处 理 如 何平 衡 数 据 及 时 
性 与 电量 的 消耗 。 


当 设 置 安排 好 更 新 操作 后 ， 可 以 使 用 不 确定 重复 提醒 的 方式 来 允许 系统 把 当前 这 个 操作 进行 
定向 移动 (比如 推迟 一 会 ) 。 


int alarmType = AlarmManager.ELAPSED REALTIME; 
long interval - AlarmManager.INTERVAL HOUR; 
long start - System.currentTimeMillis() * interval; 


alarmManager.setInexactRepeating(alarmType, start, interval, pi); 


如 果 几 个 提醒 都 安排 在 某 个 点 同时 被 触发 ， 那 么 就 可 以 使 得 多 个 操作 在 同一 个 无 线 电 状态 下 
操作 完 。 


如 果 可 以 ， 请 设置 提醒 的 类 型 为 ELAPSED REALTIME 或 者 RTC 而 不 是 wAKEUP 。 通 过 一 直 等 
待 知道 手机 在 提醒 通知 触发 之 前 不 再 处 于 standby 模式 ， 进 一 步 地 减少 电量 的 消耗 。 


pao LARGE UL app 被 使 用 的 频率 来 有 选择 性 地 减少 更 新 的 频率 ， 从 而 降低 这 
通知 的 影响 。 


另 一 个 方法 是 在 app 在 上 一 次 更 新 操作 之 后 还 未 被 使 用 的 情况 下 ， 使 用 指数 退 避 算法 
exponential back-off algorithm 来 减少 更 新 频率 。 断 言 一 个 最 小 的 更 新 频率 和 任何 时 候 使 用 
app 都 去 重 置 频率 通常 都 是 有 用 的 方法 。 例 如 


SharedPreferences sp = 
context.getSharedPreferences(PREFS, Context.MODE WORLD READABLE); 


boolean appUsed = sp.getBoolean(PREFS APPUSED, false); 
long updateInterval - sp.getLong(PREFS INTERVAL, DEFAULT REFRESH INTERVAL); 


if (!appUsed) 
if ((updateInterval *= 2) > MAX REFRESH INTERVAL) 
updateInterval - MAX REFRESH INTERVAL; 


Editor spEdit - sp.edit(); 
spEdit.putBoolean(PREFS APPUSED, false); 
spEdit.putLong(PREFS INTERVAL, updateInterval); 
spEdit.apply(); 


rescheduleUpdates(updateInterval); 
executeUpdateOrPrefetch(); 


初始 化 一 个 网 络 连接 的 花费 不 会 因为 是 否 成 功 下 载 了 数据 而 改变 。 对 于 那些 成 功 完成 是 很 重 
要 的 时 间 敏 感 的 传输 ， 我 们 可 以 使 用 指数 退 避 算法 来 减少 重复 尝试 的 次 数 ， 这 样 能 够 避免 浪 
费 电 量 。 例 如 


private void retryIn(long interval) { 
boolean success - attemptTransfer(); 


if (!success) { 
retryIn(interval*2 « MAX RETRY INTERVAL ? 
interval*2 : MAX RETRY INTERVAL); 


另外 ， 对 于 可 以 容忍 失败 连接 的 传输 (例如 定期 更 新 ) ， 我 们 可 以 简单 地 忽略 失败 的 连接 和 
传输 尝试 。 


笔者 结语 :这 一 课 讲 到 GCM 与 指数 退 避 算法 等 ， 其 实 这 些 细节 很 值得 我 们 注意 ， 如 果 能 在 实际 
项 目 中 加 以 应 用 ， 很 明显 程序 的 质量 上 升 了 一 个 档次 ! 


重复 的 下 载 是 宛 余 的 


编写 :kesenhoo - 原文 :http://developer.android.com/training/efficient- 
downloads/redundant redundant.html 


减少 下 载 的 最 基本 方法 是 仅仅 下 载 那 些 我 们 需要 的 。 从 数据 的 角度 看 ， 我 们 可 以 通过 传递 类 
似 上 次 更 新 时 间 这 样 的 参数 来 制定 查询 数据 的 条 件 。 


同样 ， 在 下 载 图 片 的 时 候 ，server 那 边 最 好 能 够 减少 图 片 的 大 小 ， 而 不 是 让 我 们 下 载 完整 大 
小 的 图 片 。 


缓存 文件 到 本 地 


另 一 个 重要 的 技术 是 避免 下 载重 复 的 数据 。 可 以 使 用 缓存 机 制 来 处 理 这 个 问题 。 缓 存 静 态 的 
ROUEN TuS Acide 。 这 些 缓存 的 资源 需要 分 开 存 放 ， 使 
得 我 们 可 以 定期 地 清理 这 些 缓存 ， 从 而 控制 缓存 数据 的 大 小 。 


为 了 保证 app 不 会 因为 缓存 而 导致 显示 的 是 上 加 数据， 请 在 缓存 中 获取 数据 的 同时 检测 其 是 否 
过 期 ， 当 数据 过 期 的 时 候 ， 会 提示 进行 刷新 。 

long currentTime = System.currentTimeMillis(); 

HttpURLConnection conn - (HttpURLConnection) url.openConnection(); 


long expires - conn.getHeaderFieldDate("Expires", currentTime); 
long lastModified = conn.getHeaderFieldDate("Last-Modified", currentTime); 


setDataExpirationDate(expires); 
if (lastModified < lastUpdateTime) { 
// Skip update 


else { 
// Parse update 


} 


使 用 这 种 方法 ， 可 以 有 效 保证 缓存 里 面 一 直 是 最 新 的 数据 。 


我 们 可 以 缓存 非 敏 感 数 据 到 非 受 管 的 外 部 缓存 目录 (目录 会 是 sdcard 下 面 


的 Android/data/data/com.xxx.xxx/cache ) 


Context.getExternalCacheDir(); 


或 者 ， 我 们 可 以 使 用 受 管 /安全 的 应 用 缓存 。 请 注意 ， 当 系统 的 可 用 存储 空间 较 小 时 ， 存 放 在 
内 存 中 的 数据 有 可 能 会 被 清除 (类 似 : system/data/data/com.xxx.xxx. /cache ) 


Context.getCache(); 


缓存 在 上 面 两 个 地 方 的 文件 都 会 在 app Sp R i 1 RR aH © 


Ps : 请 注意 这 点 :发 现 很 多 应 用 总 是 随便 在 sdcard 下 面 创建 一 个 目录 用 来 存放 缓存 ， 可 是 这 
些 缓存 又 不 会 随 着 程序 的 印 载 而 被 删除 ， 这 其 实 是 不 符合 规范 ， 程 序 都 被 印 载 了 ， 为 何 还 要 
留 那么 多 垃圾 文件 ， 而 且 这 些 文件 有 可 能 会 泄漏 一 些 隐 私信 息 。 除 非 你 的 程序 是 音乐 下 载 ， 
拍照 程序 等 等 ， 这 些 确定 程序 生成 的 文件 是 会 被 用 户 需要 留 下 的 ， 不 然 都 应 该 使 用 上 面 的 那 
种 方式 来 获取 Cache 目录 。 


使 用 HttpURLConnection 响应 缓存 


在 Android 4.0 里 面 为 HttpURLConnection 增加 了 一 个 响应 缓存 (这 是 一 个 很 好 的 减少 http 
请 求 次 数 的 机 制 ，Android 官方 推荐 使 用 HttpURLConnection 而 不 是 Apache 的 
DefaultHttpClient， 就 是 因为 前 者 不 仅仅 有 针对 android 做 http 请 求 的 优化 ， 还 在 4.0 上 增加 
了 Reponse Cache， 这 进一步 提高 了 效率 )。 我 们 可 以 使 用 反射 机 制 开启 HTTP response 
cache， 看 下 面 的 例子 : 


private void enableHttpResponseCache() { 
try { 
long httpCacheSize - 10 * 1024 * 1024; // 10 MiB 
File httpCacheDir - new File(getCacheDir(), "http"); 
Class.forName("android.net.http.HttpResponseCache") 
.getMethod("install", File.class, long.class) 
.invoke(null, httpCacheDir, httpCacheSize); 
catch (Exception httpResponseCacheNotAvailable) { 
Log.d(TAG, "HTTP response cache is unavailable."); 
} 
} 


上 面 的 示例 代码 在 Android 4.0 以 上 的 设备 上 会 开启 response cache， 同 时 不 会 影响 到 之 前 
的 程序 。 

在 cache 被 开启 之 后 ， 所 有 cache 中 的 HTTP 请 求 都 可 以 直接 在 本 地 存储 中 进行 响应 ， 并 不 需 
要 开启 一 个 新 的 网 络 连接 。 被 cache 起 来 的 response 可 以 被 server 所 确保 没有 过 期 ， 这 样 就 减 
少 了 下 载 所 需 的 带宽 。 


没有 被 cached 的 response 会 为 了 方便 下 次 请 求 而 被 存储 在 response cache 中 。 
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根据 网 络 连接 类 型 来 调整 下 载 模式 


编写 :kesenhoo - 原文 :http://developer.android.com/training/efficient- 
downloads/connectivity patterns.html 


所 有 的 网 络 类 型 (Wi-Fi、3G、2G 等 ) 对 电量 的 消耗 并 不 是 一 样 的 。 不 仅 是 Wi-Fi 电波 比 无 线 
电波 的 耗 电量 要 少 很 多 ， 而 且 不 同 的 无 线 电波 (3G、2G、LTE..….. ) 使 用 的 电量 也 不 同 。 


使 用 Wi-Fi 


在 大 多 数 情 况 下 ，Wi-Fi 电波 会 在 使 用 相对 较 低 电量 的 情况 下 提供 一 个 相对 较 大 的 带宽 。 
此 ， 我 们 需要 争取 尽量 使 用 Wi-Fi 来 传递 数据 。 


我 们 可 以 使 用 Broadcast Receiver 来 监听 网 络 连接 状态 的 变化 。 当 切换 为 Wi-Fi 时 ， 我 们 可 
以 进行 大 量 的 数据 传递 操作 ， 例 如 下 载 ， 执 行 定时 的 更 新 操作 ， 甚 至 是 在 这 个 时 候 暂 时 加 大 
更 新 频率 。 这 些 内 容 都 可 以 在 前 面 的 课程 中 找到 。 


使 用 更 大 的 带宽 来 更 不 频繁 地 下 载 更 乡 数 据 


当 通 过 无 线 电 进行 连接 的 时 候 ， 更 大 的 带宽 通常 伴随 着 更 多 的 电量 消耗 。 这 意味 着 LTE (一 
种 4G 网 络 制式 ) 会 比 3G 制式 更 耗 电 ， 当 然 比 起 2G BE 


从 Lesson 1 我 们 知道 了 无 线 电 状态 机 是 怎么 回 事 ， 通 常 来 说 相对 更 宽 的 带宽 网 络 制式 会 有 更 
长 的 状态 切换 时 间 (也 就 是 从 full power 过 渡 到 standby 有 更 长 一 段 时 间 的 延迟 ) o 


同时 ， 更 高 的 带宽 意味 着 可 以 更 大 量 的 进行 预 取 ， 下 载 更 多 的 数据 。 也 许 这 个 说 法 不 是 很 直 
观 ， 因 为 过 渡 的 时 间 比 较 长 ， 而 过 渡 时 间 的 长 短 我 们 无 法 控制 ， 也 就 是 过 渡 时 间 的 电量 消耗 
差不多 是 固定 了 。 既 然 这 样 ， 我 们 在 每 次 传输 会 话 中 为 了 减少 更 新 的 频率 而 把 无 线 电 激活 的 
时 间 拉 长 ， 这 样 显 的 更 有 效率 。 也 就 是 尽量 一 次 性 把 事情 做 完 ， 而 不 是 断断续续 的 请 求 。 


例如 : 如 果 LTE 无 线 电 的 带宽 与 电量 消耗 都 是 3G 无 线 电 的 2 倍 ， 我 们 应 该 在 每 次 会 话 的 时 候 
都 下 载 4 倍 于 3G 的 数据 量 ， 或 者 是 差不多 10Mb (前 面 文章 有 说 明 3G 一 般 每 次 下 载 

2Mb) 。 当 然 ， 下 载 到 这 么 多 数据 的 时 候 ， 我 们 需要 好 好 考虑 预 取 本 地 存储 的 效率 并 且 需 要 
经 常 刷新 预 取 的 缓存 。 


我 们 可 以 使 用 connectivity manager 来 判断 当前 激活 的 无 线 电 波 ， 并 且 根 据 不 同 结果 来 修改 
预 取 操 作 。 


ConnectivityManager cm = 
(ConnectivityManager)getSystemService(Context.CONNECTIVITY SERVICE); 


TelephonyManager tm - 
(TelephonyManager)getSystemService(Context.TELEPHONY SERVICE); 


NetworkInfo activeNetwork - cm.getActiveNetworkInfo(); 
int PrefetchCacheSize - DEFAULT PREFETCH CACHE; 


switch (activeNetwork.getType()) { 
case (ConnectivityManager.TYPE WIFI): 
PrefetchCacheSize - MAX PREFETCH CACHE; break; 
case (ConnectivityManager.TYPE MOBILE): { 
switch (tm.getNetworkType()) { 
case (TelephonyManager.NETWORK TYPE LTE | 
TelephonyManager.NETWORK TYPE HSPAP): 
PrefetchCacheSize *- 4; 
break; 
case (TelephonyManager.NETWORK TYPE EDGE | 
TelephonyManager.NETWORK TYPE GPRS): 
PrefetchCacheSize /- 2; 
break; 
default: break; 
} 


break; 


} 
default: break; 


Ps: 想 要 最 大 化 效率 与 最 小 化 电量 的 消耗 ， 需 要 考虑 的 东西 太 多 了 ， 通 常 来 说 ， 会 根据 app 
的 动能 需求 来 选择 有 所 侧重 ， 那么 前 i0 leh es 影响 比较 大 ,这 有 利于 
我 们 做 出 最 优选 择 。 


云 同 步 


编写 :kesenhoo，jdneo - 原 
x-:http://developer.android.com/training/cloudsync/index.html 


通过 为 网 络 连接 提供 强大 的 API * Android Framework 可 以 帮助 我 们 建立 丰富 的 、 具 有 云 功能 
的 App。 这 些 App 可 以 同步 数据 到 远程 服务 器 端 ， 确 保 我 们 所 有 的 设备 都 能 保持 数据 同步 ， 
并 且 重 要 的 数据 都 能 够 备份 在 云端 。 


本 章节 会 介绍 几 种 不 同 的 策略 来 实现 具有 云 功能 的 App 。 包 括 : 使 用 我 们 自己 的 后 端 网 络 应 
用 进行 数据 云 同步 ， 以 及 使 用 云 对 数据 进行 备份 。 这 样 的 话 ， 当 用 户 将 我 们 的 app 安装 到 一 
台新 的 设备 上 时 ， 他 们 之 前 的 使 用 数据 就 可 以 得 到 恢复 了 。 


Lessons 


e 使 用 备份 API 


学 习 如 何 将 Backup API 集成 到 应 用 中 。 通 过 ESO API 可 以 将 用 户 数 据 (比如 配置 信 
息 、 笔 记 、 高 分 记录 等 ) 无 颖 地 在 多 台 设 备 上 进行 同步 更 新 。 


e 使 用 Google Cloud Messaging (已 废弃 ) 


学 习 如 何 高 效 的 发 送 多 播 消 息 ， 如 何 正确 地 响应 接收 到 的 Google Cloud Messaging 
(GCM) 消息 ， 以 及 如 何 使 用 GCM 消 息 与 服务 器 进行 高 效 同步 。 


使 用 备份 API 


编写 :kesenhoo - 原文 :http://developer.android.com/training/cloudsync/backupapi.html 


当 用 户 购买 了 一 台新 的 设备 或 者 是 对 当前 的 设备 做 了 恢复 出 厂 设 置 的 操作 ， 用 户 会 希望 在 进 
行 初始 化 设置 的 时 候 ，Google Play 能 够 把 之 前 安装 过 的 应 用 恢复 到 设备 上 。 默 认 情 况 是 ， 用 
户 的 这 些 期 望 并 不 会 发 生 ， 他 们 之 前 的 设置 与 数据 都 会 丢失 。 


对 于 一 些 数据 量 相 对 较 少 的 情况 (通常 少 于 1MB) ， 例 如 用 户 偏好 设置 、 笔 记 、 游 戏 分 数 或 
者 是 其 他 的 一 些 状态 数据 ， 可 以 使 用 Backup API 来 提供 一 个 轻 量 级 的 解决 方案 。 这 节 课 会 介 
绍 如 何 将 Backup API 集成 到 我 们 的 应 用 当中 ， 以 及 如 何 利用 Backup API 将 数据 恢复 到 新 的 
设备 上 。 


注册 Android Backup Service 


这 节 课 中 所 使 用 的 Android Backup Service 需要 进行 注册 。 我 们 可 以 点 击 这 里 进行 注册 。 注 
册 成 功 后 ， 服 务 器 会 提供 一 段 类 似 于 下 面 的 代码 ， 我 们 需要 将 它 添加 到 应 用 的 Manifest 文件 
中 : 


<meta-data android:name-"com.google.android.backup.api key" 
android:value-z"ABCDe1FGHij2KlmN3o0PQRSATUVWb5xYZ" /> 


请 注意 ， 每 一 个 备份 Key 都 只 能 在 特定 的 包 名 下 工作 。 如 果 我 们 有 不 同 的 应 用 需要 使 用 这 个 
方法 进行 备份 ， 那 么 需要 分 别 为 他 们 进行 注册 。 


配置 Manifest 文件 


使 用 Android 的 备份 服务 需要 将 两 个 额外 的 内 容 添加 到 应 用 的 Manifest 文件 中 。 首 先 ， 声 明 
备份 代理 的 类 名 ， 然 后 添加 一 段 类 似 上 面 的 代码 作为 Application 标签 的 子 标签 。 假 设 我 们 的 
备份 代理 叫 作 TheBackupAgent ， 下 面 的 例子 展示 了 如 何在 Manifest 文件 中 添加 这 些 信息 : 


«application android:label-"MyApp" 
android: backupAgent="TheBackupAgent"> 


<meta-data android:name="com.google.android.backup.api_key" 
android: value="ABcDe1FGHij2K1mMN30PQRS4TUVW5xYZ" /> 


</application> 


编写 备份 代理 


创建 备份 代理 最 简单 的 方法 是 继承 BackupAgentHelper。 创建 这 个 帮助 类 实际 上 非常 简便 。 
首先 创建 一 个 类 ， 其 类 名 和 上 述 Manifest 文件 中 声明 的 类 名 一 致 ( 本 例 中 ， 它 叫做 
TheBackupAgent ) ， 然 后 继承 BackupAgentHelper ” 之 后 重 写 onCreate() 方法 。 


在 onCreate() 中 创建 一 个 BackupHelper。 这 些 帮 助 类 是 专门 用 来 备份 某 些 数据 的 。 目 前 
Android Framework 包含 了 两 种 帮助 类 : FileBackupHelper 与 
SharedPreferencesBackupHelper。 在 我 们 创建 一 个 帮助 类 并 且 指 向 需要 备份 的 数据 的 时 候 ， 
仅仅 需要 使 用 addHelper() 方法 将 它们 添加 到 BackupAgentHelper 当中 ， 之 后 再 增加 一 个 
Key 用 来 恢复 数据 。 大 多 数 情 况 下 ， 完 整 的 实现 差不多 只 需要 10 行 左右 的 代码 。 


下 面 是 一 个 对 高 分 数据 进行 备份 的 例子 : 


import android.app.backup.BackupAgentHelper; 
import android.app.backup.FileBackupHelper; 


public class TheBackupAgent extends BackupAgentHelper { 
// The name of the SharedPreferences file 
static final String HIGH SCORES FILENAME = "scores"; 


// A key to uniquely identify the set of backup data 
static final String FILES BACKUP KEY - "myfiles"; 


// Allocate a helper and add it to the backup agent 

@Override 

void onCreate() { 
FileBackupHelper helper - new FileBackupHelper(this, HIGH SCORES FILENAME); 
addHelper(FILES BACKUP KEY, helper); 


为 了 使 得 程序 更 加 灵活 ，FileBackupHelper 的 构造 函数 可 以 带 有 任意 数量 的 文件 名 。 我 们 只 
需 简 单 地 通过 增加 一 个 额外 的 参数 ， 就 能 实现 同时 对 最 高 分 文件 与 游戏 进度 文件 进行 备份 ， 
如 下 所 述 : 


@Override 
void onCreate() { 
FileBackupHelper helper = new FileBackupHelper(this, HIGH SCORES FILENAME, PRO 
GRESS FILENAME); 
addHelper(FILES BACKUP KEY, helper); 


备份 用 户 偏好 同样 比较 简单 。 和 创建 FileBackupHelper 一 样 来 创建 一 个 
SharedPreferencesBackupHelper。 在 这 种 情况 下 , 不 是 添加 文件 名 到 构造 函数 当中 ， 而 是 添 
加 被 应 用 所 使 用 的 Shared Preference Groups 的 名 称 。 下 面 的 例子 展示 的 是 ， 如 果 高 分 数据 
是 以 Preference 的 形式 而 非 文件 的 形式 存储 的 ， 备 份 代 理 帮 助 类 应 该 如 何 设计 : 


import android.app.backup.BackupAgentHelper; 
import android.app.backup.SharedPreferencesBackupHelper; 


public class TheBackupAgent extends BackupAgentHelper { 
// The names of the SharedPreferences groups that the application maintains. The 
se 
// are the same strings that are passed to getSharedPreferences(String, int). 
static final String PREFS DISPLAY - "displayprefs"; 
static final String PREFS SCORES - "highscores"; 


// An arbitrary string used within the BackupAgentHelper implementation to 
// identify the SharedPreferencesBackupHelper's data. 
static final String MY PREFS BACKUP KEY = "myprefs"; 





// Simply allocate a helper and install it 
void onCreate() { 
SharedPreferencesBackupHelper helper - 
new SharedPreferencesBackupHelper(this, PREFS DISPLAY, PREFS SCORES); 
addHelper(MY PREFS BACKUP KEY, helper); 





虽然 我 们 可 以 根据 喜好 增加 任意 数量 的 备份 帮助 类 到 备份 代理 帮助 类 中 ， 但 是 请 记 住 每 一 种 
类 型 的 备份 帮助 类 只 需要 一 个 就 够 了 。 一 个 FileBackupHelper 可 以 处 理 所 有 我 们 想 要 备份 的 
文件 , 而 一 个 SharedPreferencesBackupHelper 则 能 够 处 理 所 有 我 们 想 要 备份 的 Shared 
Preference Groups。 


请 求 备份 


为 了 请 求 一 个 备份 ， 仅 仅 需 要 创建 一 个 BackupManager 实例 ， 然 后 调用 它 的 dataChanged() 
方法 即 可 : 


import android.app.backup.BackupManager ; 


public void requestBackup() { 
BackupManager bm = new BackupManager(this); 
bm.dataChanged(); 


该 调用 会 告知 备份 管理 器 即将 有 数据 会 被 备份 到 云端 。 在 之 后 的 某 个 时 间 点 ， 备 份 管理 器 会 
执行 备份 代理 的 onBackup() 方法 。 无 论 任何 时 候 ， 只 要 数据 发 生 了 改变 ， 我 们 都 可 以 去 调用 
它 ， 并 且 不 用 担心 这 样 会 增加 网 络 的 负荷 。 如 果 我 们 在 备份 正式 发 生 之 前 请 求 了 两 次 备份 ， 
那么 最 终 备 份 操作 仅仅 会 出 现 一 次 。 


恢复 备份 数据 


一 般 而 言 ， 我 们 不 应 该 手动 去 请 求 恢 复 ， 而 是 应 该 让 应 用 安装 到 设备 上 的 时 候 自动 进行 恢 
复 。 然 而 ， 如 果 确 实 有 必要 手动 去 触发 恢复 ， 只 需要 调用 requestRestore() 方法 就 可 以 了 。 


使 用 Google Cloud Messaging (已 废弃 ) 


编写 :jdneo - 原文 :http://developer.android.com/training/cloudsync/gcm.html 


谷歌 云 消息 (GCM) 是 一 个 用 来 给 Android 设 备 发 送 消息 的 免费 服务 ， 它 可 以 极 大 地 提升 用 户 
体验 。 利 用 GCM 消 息 ， 你 的 应 用 可 以 一 直 保 持 更 新 的 状态 ， 同 时 不 会 使 你 的 设备 在 服务 器 端 
没有 可 用 更 新 时 ， 唤 醒 无 线 电 并 对 服务 器 发 起 轮 询 〈 这 会 消耗 大 量 的 电量 ) 。 同 时 ，GCM 可 
以 让 你 最 多 一 次 性 将 一 条 消息 发 送 给 1,000 个 人 ， 使 得 你 可 以 在 恰当 地 时 机 很 轻松 地 联系 大 量 
的 用 户 ， 同 时 大 量 地 减轻 你 的 服务 器 负担 。 


这 节 课 将 包含 一 些 把 GCM 集 成 到 应 用 中 的 最 佳 实践 方法 ， 前 提 是 假定 你 已 经 对 该 服务 的 基本 
实现 有 了 一 个 了 解 。 如 果 不 是 这 样 的 话 ， 你 可 以 先 阅 读 一 下 : GCM demo app tutorial 。 


高 效 地 发 送 多 播 消息 


一 个 GCM 最 有 用 的 特性 之 一 是 单条 消息 最 多 可 以 发 送 给 1,000 个 接收 者 。 这 个 功能 可 以 更 加 简 

单 地 将 重要 消息 发 送 给 你 的 所 有 用 户 群体 。 例 如 ， 比 方 说 你 有 一 条 消息 需要 发 送 给 1,000,000 

个 人 ， 而 你 的 服务 器 每 秒 能 发 送 500 条 消息 。 如 果 你 的 每 条 消息 只 能 发 送 给 一 个 接收 者 ， 那 么 

整个 消息 发 送 过 程 将 会 耗 时 1,000,000/500=2,000 秒 ， 大 约 半 小 时 。 然 而 ， 如 果 一 条 消息 可 以 

一 次 性 地 发 送 给 1,000 个 人 的 话 ， 那 么 耗 时 将 会 是 (1,000,000/1,000)/500=2 秒 。 这 不 仅仅 体现 

了 GCM 的 实用 性 ， 同 时 对 于 一 些 实时 消息 而 言 ， 其 重要 性 也 是 不 言 而 喻 的 。 就 比如 灾难 预 
警 或 者 体育 比分 播报 ， 如 果 延 迟 了 30 分 钟 ， 消 息 的 价值 就 大 打折 扣 了 。 


想 要 利用 这 一 功能 非常 简单 。 如 果 你 使 用 的 是 Java 语 言 版 本 的 GCM helper library， 只 需要 
向 send 或 者 sendNoRetry 方法 提供 一 个 注册 |D 的 List 就 行 了 (不 要 只 给 单个 的 注册 |D ) 


// This method name is completely fabricated, but you get the idea. 
List regIds - whoShouldISendThisTo(message); 


// If you want the SDK to automatically retry a certain number of times, use the 
// standard send method. 
MulticastResult result - sender.send(message, regIds, 5); 


// Otherwise, use sendNoRetry. 


MulticastResult result - sender.sendNoRetry(message, regIds); 


如 果 想 用 除了 Java 之 外 的 语言 实现 GCM 支 持 ， 可 以 构建 一 个 带 有 下 列 头 部 信息 的 HTTP 
POST 请 求 : 


Authorization: key=YOUR_API_KEY 
Content-type: application/json 


之 后 将 你 想 要 使 用 的 参数 编码 成 一 个 JSON 对 象 ， 列 出 所 有 在 registration ids 这 个 Key 下 的 
注册 ID。 下 面 的 代码 片段 是 一 个 例子 。 除 了 registration ids 之 外 的 所 有 参数 都 是 可 选 的 ， 
在 data 内 的 项 目 代表 了 用 户 定 义 的 载荷 数据 ， 而 非 GCM 定 义 的 参数 。 这 个 HTTP POST 消息 
将 会 发 送 到 : https://android.googleapis.com/gcm/send : 


( "collapse key": "score update", 
"time to live": 108, 
"delay while idle": true, 
"data": { 
"Scones MATTB 
"time": "115:16.2342" 


3 
"registration ids":["4", ugur "15", "16", M23 "42"] 


关于 更 多 GCM 多 播 消息 的 格式 ， 可 以 阅读 : Sending Messages » 


对 可 替换 的 消息 执行 折 重 


GCM 经 常 被 用 作为 一 个 触发 器 ， 它 告诉 移动 应 用 向 服务 器 发 起 链接 并 更 新 数据 。 在 GCM 中 ， 
可 以 (也 推荐 ) 在 新 消息 要 替代 日 消 息 时 ， 使 用 可 折 和 县 的 消息 (Collapsible Messages) 。 我 
们 用 体育 比赛 作为 例子 ， 如 果 你 向 所 有 用 户 发 送 了 一 条 包含 了 当前 比赛 比分 的 消息 ，15 分 钟 
之 后 ， 又 发 送 了 一 条 消息 更 新 比分 ， 那 么 第 一 条 消息 就 没有 意义 了 。 对 于 那些 还 没有 收 到 第 
一 条 消息 的 用 户 ， 就 没有 必要 将 这 两 条 消息 全 部 接收 下 来 ， 何 况 如 果 要 接收 两 条 消息 ， 那 么 
设备 不 得 不 进行 两 次 响应 (比如 对 用 户 发 出 通知 或 警告 ) ， 但 实际 上 两 条 消息 中 只 有 一 条 是 
重要 的 。 


当 你 定义 了 一 个 折 登 Key， 此 时 如 果 有 多 个 消息 在 GCM 服 务 器 中 ， 以 队列 的 形式 等 待 发 送 给 
同一 个 用 户 ， 那 么 只 有 最 后 的 那 一 条 消息 会 被 发 出 。 对 于 之 前 所 说 的 体育 比分 的 例子 ， 这 样 
做 能 让 设备 免 于 处 理 不 必要 的 任务 ， 也 不 会 让 设备 对 用 户 造 成 太 多 打扰 。 对 于 其 他 的 一 些 场 
景 比如 与 服务 器 同步 数据 (检查 邮件 接收 ) ， 这 样 做 的 话 可 以 减少 设备 需要 执行 同步 的 次 
数 。 例 如 ， 如 果 有 10 封 邮件 在 服务 器 中 等 待 被 接收 ， 并 且 有 10 条 GCM 消 息 发 送 到 设备 提醒 它 
有 新 的 邮件 ， 那 么 实际 上 只 需要 一 个 GCM 就 够 了 ， 因 为 设备 可 以 一 次 性 把 10 封 邮件 都 同步 
了 。 


为 了 使 用 这 一 特性 ， 只 需要 在 你 要 发 出 的 消息 中 添加 一 个 消息 折 王 Key。 如 果 你 在 使 用 GCM 
helper library， 那 么 就 使 用 Message 类 的 collapsekey(String key) 方法 。 


Message message = new Message.Builder(regId) 
.collapseKey("game4 scores") // The key for game 4. 
.ttl(600) // Time in seconds to keep message queued if device offline. 
.delayWhileIdle(true) // Wait for device to become active before sending. 
.addPayload("key1", "valuei1") 
.addPayload("key2", "value2") 
.build(); 


如 果 你 没有 使 用 GCM helperlibrary， 那 么 就 直接 在 你 要 构建 的 POST 头 部 中 添加 一 个 字段 。 
将 collapse key 作为 字段 名 ， 并 将 Key 的 名 称 作为 该 字段 的 值 。 


f= GCM YP ik A BE 


通常 ，GCM 消 息 被 用 作为 一 个 触发 器 ， 或 者 用 来 告诉 设备 ， 在 服务 器 或 者 别 的 地 方 有 一 些 待 
更 新 的 数据 。 然 而 ， 一 条 GCM 消 息 的 大 小 最 大 可 以 有 4kb， 因 此 ， 有 时 候 可 以 在 GCM 消 息 中 
放置 一 些 简单 的 数据 ， 这 样 的 话 设备 就 不 需要 再 去 和 服务 器 发 起 连接 了 。 在 下 列 条 件 都 满足 
的 情况 下 ， 我 们 可 以 将 数据 放置 在 GCM 消 息 中 : 


e 数据 的 总 大 小 在 4kb 以 内 。 
e 每 一 条 消息 都 很 重要 ， 且 需要 保留 。 
e 这 些 消息 息 不 适 得 用 于 消 ， a REA dE Be 84 M X 9 


例如 ， 短 消息 或 者 回合 制 网 游 中 玩家 的 移动 数据 等 都 是 将 数据 直接 嵌入 在 GCM 消 息 中 的 例 
子 。 而 电子 邮件 就 是 反面 例子 了 ， 因 为 电子 邮件 的 数据 量 一 般 都 大 于 4kb， 而 且 用 户 一 般 不 需 
要 对 每 一 封 新 邮件 都 收 到 一 个 GCM 提 醒 的 消息 。 


同时 在 发 送 多 播 消息 时 ， 也 可 以 考虑 这 一 方法 ， 这 样 的 话 就 不 会 导致 大 量 用 户 在 接收 到 GCM 
的 更 新 提醒 后 ， 同 时 向 你 的 服务 器 发 起 连接 。 


一 策略 不 适用 于 发 送 大 量 的 数据 ， 有 这 些 原因 : 


e 为 了 防止 恶意 软件 发 送 垃圾 消息 ，GCM 有 发 送 频率 的 限制 。 

e 无 法 保证 消息 按照 既定 的 发 送 顺序 到 达 。 

。 无 法 保证 消息 可 以 在 你 发 送 后 立即 到 达 。 假 设 设 备 每 一 秒 都 接收 一 条 消息 ， 消 息 的 大 小 
限制 在 1K， 那 么 传输 速率 为 8Bkbps， 或 者 说 是 1990 年 代 的 家 庭 拨号 上 网 的 速度 。 那 么 去 
此 大 量 的 消息 ， 一 定 会 让 你 的 应 用 在 Google Play Etg 1F > 2E R AEM © 


如 果 恰 当地 使 用 ， 直 接 将 数据 襄 入 到 GCM 消 息 中 ， 可 以 加 速 你 的 应 用 的 “感知 速度 ”， 因 为 这 
样 一 来 它 就 不 必 再 去 服务 器 获取 数据 了 。 


智能 地 响应 GCM 消 息 


你 的 应 用 不 应 该 仅仅 对 收 到 的 GCM 消 息 进 行 响应 就 够 了 ， 还 应 该 响应 地 更 智能 一 些 。 至 于 如 
何 响应 需要 结合 具体 情况 而 定 。 


不 要 太 过 激进 


当 提 醒 用 户 去 更 新 数据 时 ， 很 容易 不 小 心 从 “有 用 的 消息 " 变 成 "干扰 消息 "。 如 果 你 的 应 用 使 用 
状态 栏 通知 ， 那 么 应 该 更 新 现 有 的 通知 ， 而 不 是 创建 第 二 个 。 如 果 你 通过 铃声 或 者 震动 的 方 
式 提醒 用 户 ， 一 定 要 设置 一 个 计时 器 。 不 要 让 应 用 每 分 钟 的 提醒 频率 超过 1 次 ， 不 然 的 话 用 户 
很 可 能 会 不 堪 其 扰 而 印 载 你 的 应 用 ， 关 机 ， 甚 至 把 手机 扔 到 河 里 。 


用 聪明 的 办 法 同步 数据 ， 别 用 策 办 法 


当 使 用 GCM 告 知 设 备 有 数据 需要 从 服务 器 下 载 时 ， 记 住 你 有 4kb 大 小 的 数据 可 以 和 消息 一 起 
发 出 ， 这 可 以 帮助 你 的 应 用 做 出 更 智能 的 响应 。 例 如， 如 果 你 有 一 个 支持 订阅 的 阅读 应 用 ， 
而 你 的 用 户 订 阅 了 100 个 源 ， 那 么 这 就 可 以 帮助 你 的 应 用 更 智能 地 决定 应 该 去 服务 器 下 载 什 么 
数据 。 下 面 的 例子 说 明了 在 GCM 载 荷 中 可 以 发 送 什 么 样 的 数据 ， 以 及 设备 可 以 做 出 什么 样 的 
RR: 


e refresh -你 的 应 用 被 告知 向 每 一 个 源 请 求 数据 。 此 时 你 的 应 用 可 以 向 100 个 不 同 的 服务 
器 发 起 获取 订阅 内 容 的 请 求 ， 或 者 如 果 你 在 服务 器 上 有 一 个 聚合 服务 ， 那 么 可 以 只 发 送 
一 个 请 求 ， 将 100 个 源 的 数据 进行 打包 并 让 设备 获取 ， 这 样 一 次 性 就 完成 更 新 。 
* refresh, freshID - 一 种 更 好 的 解决 方案 2 你 的 应 用 可 以 有 针对 性 的 完成 更 新 
* refresh, freshID, timestamp - 三 种 方案 中 最 好 的 ， 如 果 正 好 用 户 在 收 到 GCM 消 BZ By 
手动 做 了 更 新 ， 那 么 应 用 可 以 利用 时 间 玲 和 当前 的 更 新 时 间 进 行 对 比 ， 并 决定 是 否 有 必 
要 执行 下 一 步 的 行动 。 


解决 云 同步 的 保存 冲突 


编写 :jdneo - 原文 :http://developer.android.com/training/cloudsave/conflict-res.html 


这 篇 文章 将 介绍 当 应 用 使 用 Cloud Save service 存 储 数 据 到 云端 时 ， 如 何 设计 一 个 鲁 棒 性 较 高 
的 冲突 解决 策略 。 云 存储 服务 允许 我 们 为 每 一 个 在 Google 服 务 上 的 应 用 用 户 ， 存 储 他 们 的 应 
用 数据 。 应 用 可 以 通过 使 用 云 存 储 API， 从 Android 设 备 ，iOS 设 备 或 者 Web 应 用 恢复 或 更 新 这 
些 数据 。 


云 存 储 中 的 保存 和 加 载 过 程 非 常 直 接 : 它 只 是 一 个 数据 和 byte 数 组 之 间 序 列 化 转换 ， 并 将 这 些 
数组 存储 在 云端 的 过 程 。 然 而 ， 当 用 户 有 多 个 设备 ， 并 且 有 两 个 以 上 的 设备 尝试 将 它们 的 数 
据 存 储 在 云端 时 ， 这 一 保存 的 行为 可 能 会 引起 冲突 ， 因 此 我 们 必须 决定 应 该 如 何 处 理 这 类 问 
题 。 云 端 数据 的 结构 在 很 大 程度 上 决定 了 冲突 解决 方案 的 鲁 棒 性 ， 所 以 务必 小 心地 设计 我 们 
的 数据 存储 结构 ， 使 得 冲突 解决 方案 的 逻辑 可 以 正确 地 处 理 每 一 种 情况 。 


本 篇 文章 从 一 些 有 缺陷 的 解决 方案 入 手 ， 并 解释 他 们 为 何 具 有 缺陷 。 之 后 会 呈现 一 个 可 以 避 
免 冲突 的 解决 方案 。 用 于 讨论 的 例子 关注 于 游戏 ， 但 解决 问题 的 核心 思想 是 可 以 适用 于 任何 


将 数据 存储 于 云端 的 应 用 的 。 


冲突 时 获得 通知 


OnStateLoadedListener 方 法 负责 从 Google 服 务 器 下 载 应 用 的 状态 数据 。 回 调 函 
数 OnStateLoadedListeneronStateConflict 用 来 给 应 用 在 本 地 状态 和 云端 存储 的 状态 发 生 冲 突 
时 ， 提 供 了 一 个 解决 机 制 : 


@Override 

public void onStateConflict(int stateKey, String resolvedVersion, 
byte[] localData, byte[] serverData) { 
// resolve conflict, then call mAppStateClient.resolveConflict() 


此 时 应 用 必须 决定 要 保留 哪 一 个 数据 ， 或 者 它 自己 提交 一 个 新 的 数据 来 表示 合并 后 的 数据 状 
态 ， 解 决 冲突 的 逻辑 由 我 们 自己 来 实现 。 

我 们 必须 要 意识 到 云 存 储 服务 是 在 后 台 执 行 同步 的 。 所 以 我 们 应 该 确保 应 用 能 够 在 创建 这 一 
数据 的 Context 之 外 接收 回调 。 特 别 地 ， 如 果 Google Play 服务 应 用 在 后 台 检 测 到 了 一 个 冲突 ， 
该 回调 函数 会 在 下 一 次 加 载 数据 时 被 调用 ， 通 常 来 说 会 是 在 下 一 次 用 户 启动 该 应 用 时 。 


此 ， 我 们 的 云 存 储 代 码 和 冲突 解决 代码 的 设计 必须 是 和 当前 Context 无 关 的 : 也 就 是 说 当 我 
们 拿 到 了 两 个 彼此 冲突 的 数据 ， 我 们 必须 仅 通 过 数据 集 内 获取 的 数据 去 解决 冲突 ， 而 不 依赖 
于 任何 其 它 任何 外 部 Context 。 


处 理 简单 情况 


下 面 列 举 一 些 解决 冲突 的 简单 例子 。 对 于 很 多 应 用 而 言 ， 用 这 些 策略 或 者 其 变 体 就 足够 解决 
大 多 数 问题 了 : 


新 的 比 昌 的 更 有 效 : 在 一 些 情况 下 ， 新 的 数据 可 以 蔡 代 上 昌 的 数据 。 例 如 ， 如 果 数 据 代表 了 用 
户 所 选择 角色 的 衣服 颜色 ， 那 么 最 近 的 新 的 选择 就 应 该 覆盖 老 的 选择 。 在 这 种 情况 下 ， 我 们 
可 能 会 选择 在 云 存 储 数据 中 存储 时 间 戳 。 当 处 理 这 些 冲突 时 ， 选 择 时 间 惟 最 新 的 数据 ( 记 住 
要 选择 一 个 可 靠 的 时 钟 ， 并 注意 对 不 同时 区 的 处 理 ) e 


一 个 数据 好 于 其 他 数据 : 在 一 些 情况 下 ， 我 们 是 可 以 有 方法 在 若干 数据 集中 选取 一 个 最 好 
的 。 例 如 ， 如 果 数 据 代 表 了 玩家 在 赛车 比赛 中 的 最 佳 时 间 ， 那 么 显然 ， 在 冲突 发 生 时 ， 我 们 
应 该 保留 成 绩 最 好 的 那个 数据 。 


行 合并 : 有 可 能 通过 计算 两 个 数据 集 的 合并 版 本 来 解决 冲突 。 例 如 ， 1 的 数据 代表 了 用 
s 关卡 的 进度 ， 那 么 我 们 需要 的 数据 就 是 两 个 冲突 数据 的 并 集 。 这 个 方法 ， 用 户 的 
关卡 解锁 进度 就 不 会 丢失 了 。 这 里 的 例子 使 用 了 这 Eee。 s 


为 更 复杂 的 情况 设计 一 个 策略 


当 我 们 的 游戏 允许 玩家 收集 可 交换 物品 时 (比如 金币 或 者 经 验 点 数 ) ， 情 况 会 变 得 更 加 复杂 
一 些 。 我 们 来 假想 一 个 游戏 ， 叫 做 “金币 跑 酷 "， 游 戏 中 的 角色 通过 跑步 不 断 地 收集 金币 使 自己 
变 的 富有 。 每 个 收集 到 的 金币 都 会 加 入 到 玩家 的 储 普 钠 中 。 


下 面 的 章节 将 展示 三 种 在 多 个 设备 间 解 决 冲突 的 方案 : 有 两 个 看 上 去 还 不 错 ， 可 惜 最 终 还 是 
不 能 适用 于 所 有 情况 ， 最 后 一 个 解决 方案 可 以 解决 多 个 设备 间 的 数据 冲突 。 
第 一 个 尝试 : 只 保存 总 数 


首先 ， 这 个 问题 看 上 去 像 是 说 : 云 存储 的 数据 只 要 存储 金币 的 数量 就 行 了 。 但 是 如 就 只 
这 些 数据 是 可 用 的 ， 那 么 解决 冲突 的 方案 将 会 严重 受到 限制 。 此 时 最 佳 的 方案 只 能 是 在 冲突 
发 生 时 存储 数值 最 大 的 数据 。 


想 一 下 表 1 中 所 展现 的 场景 。 假 设 玩家 一 开始 有 20 枚 硬币 ， 然 后 在 设备 A 上 收集 了 10 个 ， 在 设 
Ge 。 然 后 设备 B 将 数据 存储 到 了 云端 。 当 设备 A 尝 试 去 存储 的 时 候 ， 冲 突 发 生 
了 。“ 只 保存 总 数 " 的 冲突 解决 方案 会 存储 35 作 为 这 一 数据 的 值 (两 数 之 间 最 大 的 ) © 


R1. 值 保存 最 大 的 数 〈 不 佳 的 策略 ) 


事件 设备 A 的 设备 BB 的 云端 的 实际 的 


数据 数据 数据 总 数 
开始 阶段 20 20 20 20 
玩家 在 A 设备 上 收集 了 10 个 硬币 30 20 20 30 
玩家 在 B 设 备 上 收集 了 15 个 硬币 30 35 20 45 
设备 B 将 数据 存储 至 云端 30 35 35 45 
设备 人 尝试 将 数据 存储 至 ， 发 30 35 35 45 
生 冲 突 

设备 人 通过 选择 两 数 中 最 大 的 数 来 35 35 35 45 
解 决 冲突 大 


一 策略 显然 会 失败 : 玩家 的 金币 数 从 20 变 成 35， 但 实际 上 玩家 总 共 收 集 了 25 个 硬币 (A 设 
备 10 个 ，B 设 备 15 个 ) ， 所 以 有 10 个 硬币 丢失 了 。 只 在 云端 存储 硬币 的 总 数 是 不 足以 实现 一 
个 健壮 的 冲突 解决 算法 的 。 


第 二 个 尝试 : 存储 总 数 和 变化 值 


另 一 个 方法 是 在 存储 数据 中 包括 一 些 额 bM to: 自 上 次 提交 后 硬币 增加 的 数量 
(delta) 。 在 这 一 方法 中 ， 存 储 的 数据 可 以 用 一 个 二 元 组 来 表示 (Td) ， 其 中 T 是 硬币 的 总 
数 ， 而 d 是 硬币 增加 的 数量 。 


通过 这 样 的 数据 存储 结构 ， 我 们 的 冲突 检测 算法 在 鲁 棒 性 上 会 有 更 大 的 提升 空间 。 但 是 这 个 
方法 在 某 些 情况 下 依然 会 存在 问题 。 


下 面 是 包含 delta 数 值 的 冲突 解决 算法 过 


e 本 地 数据 : (T, d) 
e 云端 数据 : (T', d) 
e 解决 后 的 数据 : (T'+d, d) 


例如 ， 当 我 们 在 本 地 状态 (Td) 和 云端 状态 (Td) 之 间 发 生 了 冲突 时 ， 可 以 将 它们 合并 成 
(T'+d, d) 。 这 意味 着 我 们 从 本 地 拿 出 delta 数 据 ， 并 将 它 和 云端 的 数据 结合 起 来 ， 竺 一 看 ， 
这 种 方法 可 以 很 好 的 计量 多 个 设备 所 收集 的 金币 。 


该 方法 看 上 去 很 可 靠 ， 但 它 在 具有 移动 网 络 的 环境 中 难以 适用 : 
e 用 户 可 能 在 设备 不 在 线 时 存储 数据 。 这 些 改变 会 以 队列 形式 等 待 手 机 联网 后 提交 。 


e 这 个 方法 的 同步 机 制 是 用 最 新 的 变化 覆盖 掉 任 何 之 前 的 变化 。 换 名 话说 ， 第 二 次 写 入 的 
变化 会 提交 到 云端 〈 当 设备 联网 了 以 后 ) ， 而 第 一 次 写 入 的 变化 就 被 忽略 了 。 


为 了 进一步 说 明 ， 我 们 考虑 一 下 表 2 所 列 的 场景 。 在 表 2 列 出 的 一 系列 操作 发 生 后 ， 云 端的 状 
将 是 (130, +5) ， 最 终 冲 突 解决 后 的 状态 是 (140, +10) 。 这 是 不 正确 的 ， 因 为 从 总 体 上 
言 ， 用 户 一 共 在 A 上 收集 了 110 枚 硬币 而 在 B 上 收集 了 120 枚 硬币 。 总 数 应 该 为 250 © 


表 2.“ 总 数 + 增 量 "策略 的 失败 案例 


设备 A 的 — 设备 B 的 。” 云端 的 ” 实际 的 


ae 数据 数据 数据 总 数 
开始 阶段 (20, x) (20, x) (20,x) | 20 
玩家 在 A 设备 上 收集 了 100 个 硬币 ven (20,x)  (20,x) 120 
玩家 在 A 设 备 上 又 收集 了 10 个 硬币 0 (20,x) (20,x) | 180 
T T (130, (125, 
玩家 在 B 设 备 上 收集 了 115 个 硬币 +10) +115) (20, x) 245 
Mm (130, (130, 
玩家 在 B 设 备 上 又 收集 了 5 个 硬币 i p (20,x) | 250 
D EUM ES (130, (130, (130, 
设备 B 将 数据 存储 至 云端 ES ME 250 
设备 A 尝试 将 数据 存储 至 云端 ， 发 生 冲 。 (130, (130, (130, | sso 
突 +10) +5) +5) 
设备 A 通过 将 本 地 的 增 量 和 云端 的 总 数 (140, (130, (140, = 
相 加 来 解决 冲突 +10) +5) +10) 


注 : X 代 表 与 该 场景 无 关 的 数据 


我 们 可 能 会 尝试 在 每 次 保存 后 不 重 置 增 量 数据 来 解决 此 问题 ， 这 样 的 话 在 每 个 设备 上 第 二 次 
存储 的 数据 就 能 够 代表 用 户 至 今 为 止 收集 到 的 所 有 硬币 。 此 时 ， 设 备 A 在 第 二 次 本 地 存储 完成 
后 ， 数 据 将 是 (130, +110) 而 不 是 (130, +10) 。 然 而 ， 这 样 做 的 话 就 会 发 生 如 表 3 所 述 的 情 
ow: 


表 3. 算法 改进 后 的 失败 案例 


事件 设备 A 的 设备 BB 的 云端 的 实际 的 


数据 数据 数据 总 数 

开始 阶段 (20, x) (20, x) (20,x) | 20 
玩家 在 A 设备 上 收集 了 100 个 硬币 ES (20x) | (20x) 120 
eue. (120, (120, 
设备 A 将 状态 存储 到 去 Eo (20, x) oy, || 120 
m E (130, (120, 
玩家 在 A 设备 上 又 收集 了 10 个 硬币 0 
"M " (130, (120, 
玩家 在 B 设 备 上 收集 了 1 个 硬币 E Quo. pues 

ee ce (120, 
设备 B 尝 试 向 云端 存储 数据 ， 发 生 冲 灾 。 VAO) Pu E | el 
设备 B 通 过 将 本 地 的 增 量 和 云端 的 总 数 。 (130, (121, (121, da 
相 加 来 解决 冲突 +110) *1) *1) 
设备 A 尝试 将 数据 存储 至 云端 ， 发 生 冲 。 (130， (121, (121, E 
& +110) +1) +1) 
设备 A 通 过 将 本 地 的 增 量 和 云端 的 总 数 。 (231, (121, (231, iss 
相 加 来 解决 冲突 +110) +1) +110) 


注 : X 代 表 与 该 场景 无 关 的 数据 

现在 我 们 碰 到 了 另 一 个 问题 : 我 们 给 予 了 玩家 过 多 的 硬币 。 这 个 玩家 拿 到 了 211 枚 硬币 ， 但 实 
际 上 他 只 收集 了 111 枚 。 

解决 办 法 : 

分 析 之 前 的 几 次 尝试 ， 我 们 发 现 这 些 策略 存在 这 样 的 缺陷 : 无 法 知晓 哪些 硬币 已 经 计数 了 ， 
哪些 硬币 没有 被 计数 ， 尤 其 是 当 多 个 设备 连续 提交 的 时 候 ， 算 法 会 出 现 混乱 。 


该 问题 的 解决 办 法 是 将 我 们 在 云端 的 数据 存储 结构 改 为 字典 类 型 ， 使 用 字符 串 + 整形 的 键 值 
对 。 每 一 个 键 值 对 都 代表 了 一 个 包含 硬币 的 “委托 人 ”， 而 总 数 就 应 该 是 将 所 有 记录 的 值 加 起 
来 。 这 一 设计 的 宗旨 是 每 个 设备 有 它 自 己 的 “委托 人 ”， 并 且 只 有 设备 自己 可 以 把 硬币 放 到 它 
的 "委托 人 ”当中 。 


字典 的 结构 是 : (Aca, B:b, Cic, ...)， 其 中 a 代表 了 “委托 人 "A 所 拥有 的 硬币 ，b 是 “委托 人 "B 所 拥 
有 的 硬币 ， 以 此 类 推 。 


这 样 的 话 ， 新 的 冲突 解决 策略 算法 将 如 下 所 示 : 


e. 本 地 数据 : (Aia, Bib, Cic, ...) 
e 云端 数据 : (Aca', B:b', C:c’, ...) 


e 解决 后 的 数据 : (A:max(a,a'), B:max(b,b'), C:max(c,c’), ...) 


例如 ， 如 果 本 地 数据 是 (A:20, B:4, C:7) 并 且 云 端 数据 是 (B:10, C:2, D:14)， 那 么 解决 冲突 后 的 
数据 将 会 是 (A:20, B:10, C:7, D:14)。 当 然 ， 应 用 的 冲突 解决 远 辑 可 以 根据 具体 的 需求 而 有 所 
差异 。 上 比如 对 于 有 一 些 应 用 ， 我 们 可 能 希望 挑选 最 小 的 值 。 

为 了 测试 新 的 算法 ， 将 它 应 用 于 任何 一 个 之 前 提 到 过 的 场景 。 你 将 会 发 现 它 都 能 取得 正确 地 
结果 。 

表 4 益 述 了 这 一 点 ， 它 使 用 了 表 3 中 所 提 到 的 场景 。 注 意 下 面 所 列 出 的 关键 点 : 

在 初始 状态 ， 玩 家 有 20 枚 硬币 。 该 数据 准确 体现 在 了 所 有 设备 和 云端 中 ， 我 们 用 字典 : 
(X:20) 来 代表 它 ， 其 中 X 我 们 不 用 太 多 关心 ， 初 始 化 的 数据 是 哪儿 来 对 该 问题 没有 影响 。 
当 玩 家 在 设备 A 上 收集 了 100 枚 硬币 ， 这 一 变化 会 作为 一 个 字典 保存 到 云端 。 字 典 的 值 是 100 
是 因为 这 就 是 玩家 在 设备 A 上 收集 的 硬币 数量 。 在 这 一 过 程 中 ， 没 有 要 执行 数据 的 计算 〈 设 备 

A 仅仅 是 将 玩家 所 收集 的 数据 汇报 给 了 云端 ) © 

每 一 个 新 的 硬币 提交 会 打包 成 一 个 与 设备 关联 的 字典 并 保存 到 云端 例如， 假设 玩家 又 在 设 
备 A 上 收集 了 100 枚 硬币 ， 那 么 对 应 字典 的 值 被 更 新 为 110。 

最 终 的 结果 就 是 ， 应 用 知道 了 玩家 在 每 个 设备 上 收集 硬币 的 总 数 。 这 样 它 就 能 轻易 地 计算 出 
实际 的 总 数 了 。 


表 4. 键 值 对 策略 的 成 功 应 用 案例 


设备 A 的 数 


设备 B 的 数 


事件 云端 的 数据 n 

开始 阶段 (X:20, x) (X:20, x) (X:20, x) 20 

玩家 在 A 设 备 上 收集 了 100 — (X:20, 

MEO (X:20) (X:20) 120 

设备 A 将 状态 存储 到 云端 MES (X:20) (X:20, A:100) 120 

玩家 在 A 设 备 上 又 收集 了 (X:20， 

ore n (X:20) (X:20, A:100) 130 

玩家 在 B 设 备 上 收集 了 1 个 C20, ME 

nei O (€20,B:1)  (X:20, A:100) 131 

设备 B 尝 试 向 云端 存储 数 (X:20， 

KE (€20,B:1)  (X:20, A:100) 131 

(X:20 USED, 

设备 B 解 决 冲突 A:100, (X:20, A:100,B:1) 131 
A:110) ES 

. E X:20 

设备 A 尝 试 将 数据 存储 至 (X:20, cet Pe 

Buc. Rer) E (X:20, A:100,B:1) 134 
(X:20, (X:20, . : 

设备 A 解 决 冲突 A:110, A:100, as aS 131 
B:1) B:1) : 


清除 你 的 数据 


在 云端 允许 存储 数据 的 大 小 是 有 限制 的 ， 所 以 在 后 续 的 论述 中 ， 我 们 将 会 关注 如 何 避 免 创 建 
过 大 的 词典 。 一 开始 ， 看 上 去 每 个 设备 只 会 有 一 条 词典 记录 ， 即 使 是 非常 激进 的 用 户 也 不 太 
会 拥有 上 千 种 不 同 的 设备 (对 应 上 千 条 字典 记录 ) 。 然 而 ， 获 取 设 备 ID 的 方法 很 难 ， 并 且 我 
们 认为 这 是 一 种 不 好 的 实践 方式 ， 所 以 我 们 应 该 使 用 一 个 安装 ID， 这 更 容易 获取 也 更 可 靠 。 

这 样 的 话 就 意味 着 ， 每 一 次 用 户 在 每 台 设备 安装 一 次 就 会 产生 一 个 ID。 假 设 每 个 键 值 对 占据 
32 字 节 ， 由 于 一 个 个 人 云 存储 缓存 最 多 可 以 有 128K 的 大 小 ， 因 此 最 多 可 以 存储 4096 条 记录 。 


在 现实 场景 中 ， 你 的 数据 可 能 更 加 复杂 。 在 这 种 情况 下 ， 存 储 数 据 的 记录 条 数 也 会 进一步 受 
到 限制 。 具 体 而 言 则 需要 取决 于 实现 ， 比 如 可 能 需要 添加 时 间 崔 来 指明 每 条 记录 是 何 时 修改 
的 。 当 你 检测 到 有 一 条 记录 在 过 去 几 个 礼拜 或 者 几 个 月 的 时 间 内 都 没有 被 修改 ， 那 么 就 可 以 
安全 地 将 金币 数据 转移 到 另 一 条 记录 中 并 删除 老 的 记录 。 


使 用 Sync Adapter 传 输 数 据 


编写 :jdneo - 原文 :http://developer.android.com/training/sync-adapters/index.html 
如 果 我 们 的 应 用 允许 Android 设备 和 网 络 服 务 器 之 间 进 行 数据 同步 ， 那么 它 无 疑 将 变 得 更 加 
实用 ， 更 加 吸引 用 户 的 注意 。 例 如 ， 将 数据 传输 到 服务 器 可 以 实现 数据 的 备份 ， 另 一 方面 ， 
从 服务 器 获取 数据 可 以 让 用 户 随时 随地 都 能 使 用 我 们 的 应 用 。 有 时 候 ， 用 户 可 能 会 觉得 在 线 
编辑 他 们 的 数据 并 将 其 发 送 到 设备 上 ， 会 是 一 件 很 方便 的 事情 ; 或 者 他 们 有 时 会 希望 将 收集 
到 的 数据 上 传 到 一 个 统一 的 存储 区 域 中 。 
尽管 我 们 可 以 设计 一 套 自己 的 系统 来 实现 应 用 中 的 数据 传输 ， 但 我 们 也 可 以 考虑 一 下 使 用 
Android 的 同步 适配器 框架 (Android's Sync Adapter Framework) 。 该 框架 可 以 用 来 帮助 管 
理 数据 ， 自 动 传 输 数 据 ， 以 及 协调 不 同 应 用 间 的 同步 问题 。 当 使 用 这 个 框架 时 ， 我 们 可 以 利 
用 它 的 一 些 特性 ， 而 这 些 特性 可 能 是 我 们 自己 设计 的 传输 方案 中 所 没有 的 : 


插件 架构 (Plug-in Architecture ) 
允许 我 们 以 可 调用 组 件 的 形式 ， 将 传输 代码 添加 到 系统 中 。 
自动 执行 (Automated Execution ) 


允许 我 们 基于 不 同 的 准则 自动 地 执行 数据 传输 ， 比 如 : 当 数 据 变更 时 ， 或 者 每 隔 固定 一 段 时 
闻 ， 亦 或 者 每 天 ， 来 自动 执行 一 次 数据 传输 。 另 外 ， 系 统 会 自动 把 当前 无 法 执行 的 传输 添加 
到 一 个 队列 中 ， 并 且 在 合适 的 时 候 运 行 它 们 。 


自动 网 络 监测 (Automated Network Checking) 
系统 只 在 有 网 络 连接 的 时 候 才 会 运行 数据 传输 。 
提升 电池 使 用 效率 : 


允许 我 们 将 所 有 的 数据 传输 任务 统一 地 进行 一 次 性 批量 传输 ， 这 样 的 话 多 个 数据 传输 任务 会 
在 同一 段 时 间 内 运行 。 我 们 应 用 的 数据 传输 任务 也 会 和 其 它 应 用 的 传输 任务 相 结合 ， 并 一 起 
传输 。 这 样 做 可 以 减少 系统 连接 网 络 的 次 数 ， 进 而 减少 电量 的 使 用 。 


账户 管理 和 授权 : 


如 果 我 们 的 应 用 需要 用 户 登 录 授权 ， 那 么 我 们 可 以 将 账户 管理 和 授权 的 功能 集成 到 数据 传输 
组 件 中 。 


本 系列 课程 将 展示 如 何 创建 一 个 Sync Adapter， 如 何 创建 一 个 绑 定 了 Sync Adapter 的 服务 
(Service) ， 如 何 提供 其 它 组 件 来 帮助 我 们 将 Sync Adapter 集成 到 框架 中 ， 以 及 如 何 通 过 不 
同 的 方法 来 运行 Sync Adapter ° 


Note : Sync Adapter 是 异步 执行 的 ， 它 可 以 定期 且 有 效 地 传输 数据 ， 但 在 实时 性 上 一 般 
难以 满足 要 求 。 如 果 我 们 想 要 实时 地 传输 数据 ， 那 么 应 该 在 AsyncTask 或 IntentService 
中 完成 这 一 任务 。 


Sample Code 


BasicSyncAdapter.zip 


Lessons 


创建 Stub 授权 器 


学 习 如 何在 我 们 的 应 用 中 添加 一 个 Sync Adapter 框架 需要 的 账户 处 理 组 件 。 这 节 课 将 展示 如 
何 简 单 地 创建 一 个 Stub Authenticator 组 件 。 


创建 Stub Content Provider 


学 习 如 何在 我 们 的 应 用 中 添加 一 个 Sync Adapter 框架 需要 的 Content Provider 组 件 。 在 这 节 
课 中 ， 假 设 我 们 的 应 用 实际 上 不 需要 使 用 Content Provider， 所 以 它 将 教 我 们 如 何 添加 一 个 
Stub 组 件 。 如 果 我 们 的 应 用 已 经 有 了 一 个 Content Provider 组 件 ， 那 么 可 以 跳 过 这 节 课 。 


创建 Sync Adapter 


学 习 如 何 将 我 们 的 数据 传输 代码 封装 到 组 件 当 中 ， 并 让 其 可 以 被 Sync Adapter 框架 自动 执 


a 
o 


执行 Sync Adapter 


学 习 如 何 使 用 Sync Adapter 框架 激活 并 调度 数据 传输 。 


创建 Stub 授权 器 


编写 :jdneo - 原文 :http://developer.android.com/training/sync-adapters/creating- 
authenticator.html 


Sync Adapter 框架 假定 我 们 的 Sync Adapter 在 同步 数据 时 ， 设 备 存储 端 关联 了 一 个 账户 ， 且 
服务 器 端 需要 进行 登录 验证 。 因 此 ， 我 们 需要 提供 一 个 叫做 授权 器 (Authenticator) 的 组 件 作 
为 Sync Adapter 的 一 部 分 。 该 组 件 会 集成 在 Android 账户 及 认证 框架 中 ， 并 提供 一 个 标准 的 
接口 来 处 理 用 户 赁 据 ， 比 如 登录 信息 。 


即使 我 们 的 应 用 不 使 用 账户 ， 我 们 仍然 需要 提供 一 个 授权 器 组 件 。 在 这 种 情况 下 ， 授 权 器 所 
处 理 的 信息 将 被 忽略 ， 所 以 我 们 可 以 提供 一 个 包含 了 方法 存根 (Stub Method) 的 授权 器 组 
件 。 同 时 我 们 需要 提供 一 个 绑 定 Service， 来 允许 Sync Adapter 框架 调用 授权 器 的 方法 。 


这 节 课 将 展示 如 何 定义 一 个 能 够 满足 Sync Adapter 框架 要 求 的 Stub 授权 器 。 如 果 我 们 想 要 
提供 可 以 处 理 用 户 账户 的 实际 的 授权 器 ， 可 以 阅读 : AbstractAccountAuthenticator 。 


添加 一 个 Stub i£ 2 204+ 


要 在 应 用 中 添加 一 个 Stub 授权 器 ， 首 先 我 们 需要 创建 一 个 继承 
AbstractAccountAuthenticator 的 类 ， 在 所 有 需要 重 写 的 方法 中 ， 我 们 不 进行 任何 处 理 ， 仅 返 
回 null 或 者 抛 出 异常 。 


下 面 的 代码 片段 是 一 个 Stub 授权 器 的 例子 : 


/* 
* Implement AbstractAccountAuthenticator and stub out all 
* of its methods 
E 
public class Authenticator extends AbstractAccountAuthenticator { 
// Simple constructor 
public Authenticator(Context context) { 
super(context); 
} 
// Editing properties is not supported 
@Override 
public Bundle editProperties( 
AccountAuthenticatorResponse r, String s) { 
throw new UnsupportedOperationException(); 
} 
// Don't add additional accounts 
@Override 
public Bundle addAccount( 
AccountAuthenticatorResponse r, 


创建 Stub 授 权 器 


String sS, 
String s2; 
String[] strings, 
Bundle bundle) throws NetworkErrorException { 
return null; 
} 
// Ignore attempts to confirm credentials 
@Override 
public Bundle confirmCredentials( 
AccountAuthenticatorResponse r, 
Account account, 
Bundle bundle) throws NetworkErrorException { 
return null; 
} 
// Getting an authentication token is not supported 
@Override 
public Bundle getAuthToken( 
AccountAuthenticatorResponse r, 
Account account, 
Strang s; 
Bundle bundle) throws NetworkErrorException { 
throw new UnsupportedOperationException(); 
} 
// Getting a label for the auth token is not supported 
@Override 
public String getAuthTokenLabel(String s) { 
throw new UnsupportedOperationException(); 
} 
// Updating user credentials is not supported 
@Override 
public Bundle updateCredentials( 
AccountAuthenticatorResponse r, 
Account account, 
String s, Bundle bundle) throws NetworkErrorException { 
throw new UnsupportedOperationException(); 
J 
// Checking features for the account is not supported 
@Override 
public Bundle hasFeatures( 
AccountAuthenticatorResponse r, 
Account account, String[] strings) throws NetworkErrorException { 
throw new UnsupportedOperationException(); 
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为 了 让 Sync Adapter 框架 可 以 访问 我 们 的 授权 器 ， 我 们 必须 为 它 创建 一 个 绑 定 服务 。 这 一 服 
务 提供 一 个 Android Binder 对 象 ， 多 许 框架 调用 我 们 的 授权 器 ， 并 且 在 授权 器 和 框架 间 传 递 
数据 。 


为 框架 会 在 它 第 一 次 需要 访问 授权 器 时 启动 该 Service， 所 以 我 们 也 可 以 使 用 该 服务 来 实例 
化 授权 器 。 具 体 而 言 ， 我 们 需要 在 服务 的 Service.onCreate() 方法 中 调用 授权 器 的 构造 函 
数 。 


下 面 的 代码 样 例 展 示 了 如 何 定 义 绑 定 Service : 


jas 

* A bound Service that instantiates the authenticator 
* when started. 

i 

public class AuthenticatorService extends Service { 


// Instance field that stores the authenticator object 
private Authenticator mAuthenticator; 
QOverride 
public void onCreate() { 
// Create a new authenticator object 
mAuthenticator - new Authenticator(this); 


/* 
* When the system binds to this Service to make the RPC call 
* return the authenticator's IBinder. 

27; 

@Override 

public IBinder onBind(Intent intent) { 

return mAuthenticator.getIBinder(); 


} 


添加 授权 器 的 元 数据 (Metadata) 文件 


若 要 将 我 们 的 授权 器 组 件 集成 到 Sync Adapter 框架 和 账户 框架 中 ， 我 们 需要 为 这 些 框架 提供 
带 有 描述 组 件 信 息 的 元 数据 。 该 元 数据 声明 了 我 们 为 Sync Adapter 创建 的 账户 类 型 以 及 系统 
所 显示 的 UI 元 素 〈 如 果 硕 望 用 户 可 以 看 到 我 们 创建 的 账户 类 型 ) 。 在 我 们 的 项 目 目录 

/res/xnl/ 下 ， 将 元 数据 声明 于 一 个 XML 文件 中 。 我 们 可 以 自己 为 该 文件 按 命名 ， 通 常 我 们 


将 它 命 名 为 authenticator.xml ? 
在 这 个 XML 文件 中 ， 包 含 了 一 个 <account-authenticator> 标签 ， 它 有 下 列 一 些 属性 : 


android:accountType 


Sync Adapter 框架 要 求 每 一 个 适配器 都 有 一 个 域名 形式 的 账户 类 型 。 框 架 会 将 它 作 为 Sync 
Adapter 内 部 标识 的 一 部 分 。 如 果 服 务 端 需要 登陆 ， 账 户 类 型 会 和 账户 一 起 发 送 到 服务 端 作为 


登录 凭据 的 一 部 分 。 


如 果 我 们 的 服务 端 不 需要 登录 ， 我 们 仍然 需要 提供 一 个 账户 类 型 (该 属性 的 值 用 我 们 能 控制 
的 一 个 域名 即 可 ) 。 虽 然 框 架 会 使 用 它 来 管理 Sync Adapter， 但 该 属性 的 值 不 会 发 送 到 服务 


android:icon 


指向 一 个 包含 图 标的 Drawable 资源 。 如 果 我 们 在 res/xml/syncadapter.xml 中 通过 指定 
android:userVisible-"true" 让 Sync Adapter 可 见 ， 那 么 我 们 必须 提供 图 标 资 源 。 它 会 在 系 
统 的 设置 中 的 账户 (Accounts) 这 一 栏 内 显示 。 


android:smalllcon 


指向 一 个 包含 微小 版 本 图 标的 Drawable 资源 。 当 屏幕 尺寸 较 小 时 ， 这 一 资源 可 能 会 替代 
android:icon 中 所 指定 的 图 标 资 源 。 


android:label 


89] 了 用 户 账 户 类 型 的 本 地 化 字符 串 。 如 果 我 们 在 res/xml/syncadapter.xml 中 通过 指定 
android:userVisible-"true" 让 Sync Adapter 可 见 ， 那 么 我 们 需要 提供 该 字符 串 。 它 会 在 系 
统 的 设置 中 的 账户 这 一 栏 内 显示 ， 就 在 我 们 为 授权 器 定义 的 图 标 旁 边 。 


下 面 的 代码 样 例 展 示 了 我 们 之 前 为 授权 器 创建 的 XML 文件 : 


«?xml version="1.0" encoding="utf-8"?> 

<account-authenticator 
xmlns:android-"http://schemas.android.com/apk/res/android" 
android:accountType-z"example.com" 
android:icon-"Qdrawable/ic launcher" 
android:smalllIcon-"Qdrawable/ic launcher" 
android:label-"Qstring/app name"/» 


在 Manifest 文件 中 声明 授权 器 


在 之 前 的 步骤 中 ， 我 们 已 经 创建 了 一 个 绑 定 服务 ， 将 授权 器 和 Sync Adapter 框架 连接 了 起 
来 。 为 了 让 系统 可 以 识别 该 服务 ， 我 们 需要 在 Manifest 文件 中 添加 <service> 标签 ， 将 它 作 
为 «application» 的 子 标签 : 


«service 
android:name="com.example.android.syncadapter .AuthenticatorService"> 
<intent-filter> 
«action android:name-"android.accounts.AccountAuthenticator"/» 
</intent-filter> 
<meta-data 
android:name="android.accounts.AccountAuthenticator" 
android: resource="@xml/authenticator" /> 
</service> 


<intent-filter> 标签 配置 了 一 个 可 以 被 android.accounts.AccountAuthenticator 这 一 
Action 所 激活 的 过 滤器 ， 这 一 Intent 会 在 系统 要 运行 授权 器 时 由 系统 发 出 。 当 过 滤器 被 激活 
后 ， 系 统 会 启动 Authenticatorservice ， 即 之 前 用 来 封装 授权 器 的 Service » 


<meta-data> 标签 声明 了 授权 器 的 元 数据 。android:name 属性 将 元 数据 和 授权 器 框架 连接 起 
来 。android:resource 指定 了 我 们 之 前 所 创建 的 授权 器 元 数据 文件 的 名 字 。 


除了 授权 器 之 外 ，Sync Adapter 框架 也 需要 一 个 Content Provider。 如 果 我 们 的 应 用 并 没有 
使 用 Content Provider， 那 么 可 以 阅读 下 一 节 课 程 学 习 如 何 创建 一 个 Stub Content Provider : 
如 果 我 们 的 应 用 已 经 使 用 了 ContentProvider， 可 以 直接 阅读 : 创建 Sync Adapter 。 


创建 Stub Content Provider 


编写 :jdneo - /$ xc:http://developer.android.com/training/sync-adapters/creating-stub- 
provider.html 


Sync Adapter 框架 是 设计 成 用 来 和 设备 数据 一 起 工作 的 ， 而 这 些 设备 数据 应 该 被 灵活 且 安 全 
的 Content Provider 框架 管理 。 因 此 ，Sync Adapter 框架 会 期 望 应 用 已 经 为 它 的 本 地 数据 定 
义 了 Content Provider。 如 果 Sync Adapter 框架 尝试 去 运行 我 们 的 Sync Adapter， 而 我 们 的 
应 用 没有 一 个 Content Provider 的 话 ， 那 么 Sync Adapter 将 会 崩溃 。 


如 果 我 们 正在 开发 一 个 新 的 应 用 ， 它 将 数据 从 服务 器 传输 到 一 台 设 备 上 ， 那 么 我 们 务必 考虑 
将 本 地 数据 存储 于 Content Provider 中 。 除 了 它 对 于 Sync Adapter 的 重要 性 之 外 ，Content 
Provider 还 可 以 提供 许多 安全 上 的 好 处 ， 更 何况 它 是 专门 为 了 在 Android 设备 上 处 理 数据 存 
储 而 设计 的 。 要 学 习 如 何 创建 一 个 Content Provider， 可 以 阅读 : Creating a Content 
Provider ° 


然而 ， 如 果 我 们 已 经 通过 别 的 形式 来 存储 本 地 数据 ， 我 们 仍然 可 以 使 用 Sync Adapter X 4b 3€ 
数据 传输 。 为 了 满足 Sync Adapter 框架 对 于 Content Provider 的 要 求 ， 我 们 可 以 在 应 用 中 添 
加 一 个 Stub Content Provider。 一 个 Stub Content Provider 实现 了 Content Provider "^ ， 但 
是 所 有 的 方法 都 返回 null 或 者 o 。 如 果 我 们 添加 了 一 个 Stub Content Provider， 那 么 

论 数据 存储 机 制 是 什么 ， 我 们 都 可 以 使 用 Sync Adapter 来 传输 数据 。 


如 果 在 我 们 的 应 用 中 已 经 有 了 一 个 Content Provider， 那 么 我 们 就 不 需要 创建 Stub Content 
RA 了 。 在 这 种 情况 下 ， 我 们 可 以 略 过 这 节 课 程 ， 直 接 进 入 : 创建 Sync Adapter » t R 

还 没有 创建 Content Provider， 这 节 课 将 向 你 展示 如 何 通过 添加 一 个 Stub Content 
Provider， 将 你 的 Sync Adapter 添加 到 框架 中 。 


添加 一 个 Stub Content Provider 


要 为 我 们 的 应 用 创建 一 个 Stub Content Provider， 首 先 继承 ContentProvider 类 ， 并 且 在 所 有 
需要 重 写 的 方法 中 ， 我 们 一 律 不 进行 任何 处 理 而 是 直接 返回 。 下 面 的 代码 片段 展示 了 我 们 应 
该 如 何 创 建 一 个 Stub Content Provider : 


* Define an implementation of ContentProvider that stubs out 
* all methods 
* 
public class StubProvider extends ContentProvider { 
[= 
* Always return true, indicating that the 
* provider loaded correctly. 


创建 Stub Content Provider 


a7, 
@Override 
public boolean onCreate() { 
return true; 


/* 
* Return an empty String f 
EA 

@Override 

public String getType() { 

return new String(); 

} 

/* 

* query() always returns n 
2 
@Override 
public Cursor query( 
Wigs Ua, 
String[] projection 
String selection, 


or MIME type 


o results 


td 


String[] selectionArgs, 


String sortOrder) { 
return null; 


y 
* insert() always returns 
BX 
@Override 
public Uri insert(Uri uri, 
return null; 


/* 
* delete() always returns 
1 

@Override 

public int delete(Uri uri, 

f;e turmae 


f es 
* update() always returns 
A 
public int update( 
Uriuri 
ContentValues value 
String selection, 


null (no URI) 


ContentValues values) { 


"no rows affected" (0) 


String selection, String[] selectionArgs) ( 


"no rows affected" (0) 


5, 


String[] selectionArgs) ( 


KecuUnn 0); 
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在 Manifest 清单 文件 中 声明 Provider 


Sync Adapter 框架 会 通过 查看 应 用 的 manifest 文件 中 是 否 声明 了 provider， 来 验证 我 们 的 应 
用 是 否 使 用 了 Content Provider » A 1 # manifest 清单 文件 中 声明 我 们 的 Stub Content 
Provider ， 添 加 一 个 <provider> 标签 ， 并 让 它 拥 有 下 列 属性 字段 : 


android:name="com.example,android.datasync,.provider.StubProvider" 


指定 实现 Stub Content Provider 类 的 完整 包 名 。 


android:authorities-"com.example.android.datasync.provider" 


指定 Stub Content Provider 的 URI Authority。 用 应 用 的 包 名 加 上 字符 串 "provider" 作为 
该 属性 字段 的 值 。 虽 然 我 们 在 这 里 向 系统 声明 了 Stub Content Provider， 但 是 不 会 党 试 访 问 
Provider 本 身 。 


android:exported-"false" 


确定 其 它 应 用 是 否 可 以 访问 Content Provider » *t-F Stub Content Provider 而 言 ， 由 于 没有 
让 其 它 应 用 访问 该 Provider 的 必要 ， 所 以 我 们 将 该 值 设 置 为 false 。 该 值 并 不 会 影响 Sync 
Adapter 框架 和 Content Provider Z Ñ iJ XZ ° 


android:syncable="true" 


该 标识 指明 Provider 是 可 同步 的 。 如 果 将 这 个 值 设 置 为 true ， 那 么 将 不 需要 在 代码 中 调用 
setlsSyncable()。 这 一 标识 将 会 允许 Sync Adapter 框架 和 Content Provider 进行 数据 传输 * 
但 是 仅仅 在 我 们 显 式 地 执行 相关 调用 时 ， 这 一 传输 时 才 会 进行 。 


下 面 的 代码 片段 展示 了 我 们 应 该 如 何 将 <provider> 标签 添加 到 应 用 的 manifest 清单 文件 
v: 


«manifest xmlns:android-"http://schemas.android.com/apk/res/android" 
package-z"com.example.android.network.sync.BasicSyncAdapter" 
android: versionCode="1" 
android: versionName="1.0" > 
<application 

android:allowBackup="true" 
android:iconz"Qdrawable/ic launcher" 
android: label="@string/app_name" 
android: theme="@style/AppTheme" > 


<provider 
android: name="com.example.android.datasync. provider .StubProvider" 
android: authorities="com.example.android.datasync.provider" 
android:exported="false" 
android: syncable="true"/> 


</application> 
</manifest> 


现在 我 们 已 经 创建 了 所 有 Sync Adapter 框架 所 需要 的 依赖 项 ， 接 下 来 我 们 可 以 创建 封装 数据 
传输 代码 的 组 件 了 。 该 组 件 就 叫做 Sync Adapter 。 在 下 节 课 中 ， 我 们 将 会 展示 如 何 将 这 一 组 
件 添加 到 应 用 中 。 


创建 Sync Adpater 


编写 :jdneo - 原文 :http://developer.android.com/training/sync-adapters/creating-sync- 
adapter.html 


设备 和 服务 器 之 间 执 行 数据 传输 的 代码 会 封装 在 应 用 的 Sync Adapter 组 件 中 。Sync Adapter 
框架 会 基于 我 们 的 调度 和 触发 操作 ， 运 行 Sync Adapter 组 件 中 的 代码 。 要 将 同步 适 配 组 件 添 
加 到 应 用 当中 ， 我 们 需要 添加 下 列 部 件 : 


Sync Adapter 类 

将 我 们 的 数据 传输 代码 封装 到 一 个 与 Sync Adapter 框架 兼容 的 接口 当中 。 

绑 定 Service 

通过 一 个 绑 定 服务 ， 允 许 Sync Adapter 框架 运行 Sync Adapter 类 中 的 代码 。 

Sync Adapter 的 XML 元 数据 文件 

该 文件 包含 了 有 关 Sync Adapter 的 信息 。 框 架 会 根据 该 文件 确定 应 该 如 何 加 载 并 调度 数据 传 
输 任 务 。 

应 用 manifest 清单 文件 的 声明 

需要 在 应 用 的 manifest 清单 文件 中 声明 绑 定 服务 ; 同时 还 需要 指出 Sync Adapter 的 元 数据 。 


这 节 课 将 会 向 我 们 展示 如 何 定义 他 们 。 


创建 一 个 Sync Adapter 类 


在 这 部 分 课程 中 ， 我 们 将 会 学 习 如 何 创建 封装 了 数据 传输 代码 的 Sync Adapter 类 。 创 建 该 类 
需要 继承 Sync Adapter 的 基 类 ; 为 该 类 定义 构造 函数 ; 以 及 实现 相关 的 方法 。 在 这 些 方法 
中 ， 我 们 定义 数据 传输 任务 。 


继承 Sync Adapter X X : AbstractThreadedSyncAdapter 


要 创建 Sync Adapter 组 件 ， 首 先 继承 AbstractThreadedSyncAdapter， 然 后 编写 它 的 构造 函 
数 。 与 使 用 Activity.onCreate() 配置 Activity 时 一 样 ， 每 次 我 们 重新 创建 Sync Adapter 组 件 
的 时 候 ， 使 用 构造 函数 执行 相关 的 配置 。 例 如 ， 如 果 我 们 的 应 用 使 用 一 个 Content Provider 
来 存储 数据 ， 那 么 使 用 构造 函数 来 获取 一 个 ContentResolver 实例 。 由 于 从 Android 3.0 开始 
添加 了 第 二 种 形式 的 构造 函数 ， 来 支持 parallelsyncs 参数 ， 所 以 我 们 需要 创建 两 种 形式 的 
构造 函数 来 保证 兼容 性 。 





| Sync Adpater 


Note : Sync Adapter 框架 是 设 rmm Sync Adapter 组 件 的 单 例 一 起 工作 的 。 实 例 化 
Sync Adapter 组 件 的 更 多 细节 ， 会 在 后 面 的 章节 中 展开 。 


下 面 的 代码 展示 了 如 何 实现 AbstractThreadedSyncAdapter 和 它 的 构造 函数 


ys 
* Handle the transfer of data between a server and an 


if 
public class SyncAdapter extends AbstractThreadedSyncAdapter { 


app, using the Android sync adapter framework. 


// Global variables 
// Define a variable to contain a content resolver instance 
ContentResolver mContentResolver; 
VENUE 
* Set up the sync adapter 
i 
public SyncAdapter(Context context, boolean autoInitialize) { 
super(context, autoInitialize); 
yes 
* If your app uses a content resolver, get an instance of it 
* from the incoming Context 
A 
mContentResolver - context.getContentResolver(); 


/** 
* Set up the sync adapter. This form of the 
* constructor maintains compatibility with Android 3.0 
* and later platform versions 
5 
public SyncAdapter( 
Context context, 
boolean autoInitialize, 
boolean allowParallelSyncs) { 
super(context, autoInitialize, allowParallelSyncs); 
/* 
* If your app uses a content resolver, get an instance of it 
* from the incoming Context 
i 
mContentResolver - context.getContentResolver(); 


在 onPerformSync() 中 添加 数据 传输 代码 


Sync Adapter 组 件 并 不 会 自动 地 执行 数据 传输 。 它 对 我 们 的 数据 传输 代码 进行 封装 ， 使 得 
Sync Adapter 框架 可 以 在 后 台 执 行 数据 传输 ， 而 不 会 牵连 到 我 们 的 应 用 。 当 框架 准备 同步 我 
们 的 应 用 数据 时 ， 它 会 调用 我 们 所 实现 的 onPerformSync() 方法 。 


为 了 便于 将 数据 从 应 用 程序 转移 到 Sync Adapter 组 件 中 ，Sync Adapter 框架 调用 
onPerformSync()， 它 具有 下 面 的 参数 : 


Account 


该 Account 对 象 与 触发 Sync Adapter 的 事件 相关 联 。 如 果 服 务 端 不 需要 使 用 账户 ， 那 么 我 们 
不 需要 使 用 这 个 对 象 内 的 信息 。 


Extras 
一 个 Bundle 对 象 ， 它 包含 了 一 些 标识 ， 这 些 标识 由 触发 Sync Adapter 的 事件 所 发 送 。 
Authority 


系统 中 某 个 Content Provider 的 Authority。 我 们 的 应 用 必须 要 有 访问 它 的 权限 。 通 常 ， 该 
Authority 对 应 于 应 用 的 Content Provider ° 


Content provider client 


ContentProviderClient 针对 于 由 Authority 参数 所 指向 的 Content 
Provider。ContentProviderClient 是 一 个 Content Provider 的 轻 量 级 共有 接口 。 它 的 基本 功能 
和 ContentResolver 一 样 。 如 果 我 们 正在 使 用 Content Provider 来 存储 应 用 数据 ， 那 么 我 们 
可 以 利用 它 连接 Content Provider。 反 之 ， 则 将 其 忽略 。 


Sync result 
一 个 SyncResult 对 象 ， 我 们 可 以 使 用 它 将 信息 发 送 给 Sync Adapter 框架 。 


下 面 的 代码 片段 展示 了 onPerformSync() 函数 的 整体 结构 : 


/* 
* Specify the code you want to run in the sync adapter. The entire 
* sync adapter runs in a background thread, so you don't have to set 
* up your own background processing. 
2 
@Override 
public void onPerformSync( 
Account account, 
Bundle extras, 
String authority, 
ContentProviderClient provider, 
SyncResult syncResult) { 
/* 
* Put the data transfer code here. 
i 


虽然 实际 的 onPerformSync() 实现 是 要 根据 应 用 数据 的 同步 需求 以 及 服务 器 的 连接 协议 来 制 
定 ， 但 是 我 们 的 实现 只 需要 执行 一 些 常规 任务 : 


连接 到 一 个 服务 器 


尽管 我 们 可 以 假定 在 aia 数据 时 ， 已 经 获取 到 了 网 络 连接 ， 但 是 Sync Adapter 框架 并 不 
会 自动 地 连接 到 一 个 服务 器 


下 载 和 上 传 数 据 


Sync Adapter 不 会 自动 执行 数据 传输 。 如 果 我 们 想 要 从 服务 器 下 载 数据 并 将 它 存储 到 
Content Provider 中 ， 我 们 必须 提供 请 求 数据 ， 下 载 数据 和 将 数据 插入 到 Provider 中 的 代 
码 。 类 似 地 ， 如 果 我 们 想 把 数据 发 送 到 服务 器 ， 我 们 需要 从 一 个 文件 ， 数 据 库 或 者 Provider 
中 读 取 数据 ， 并 且 发 送 必 需 的 上 传 请 求 。 同 时 我 们 还 需要 处 理 在 执行 数据 传输 时 所 发 生 的 网 
络 错误 。 


处 理 数据 冲突 或 者 确定 当前 数据 的 状态 


Sync Adapter 不 会 自动 地 解决 服务 器 数据 与 设备 数据 之 间 的 冲突 。 同 时 ， 它 也 不 会 自动 检测 
服务 器 上 的 数据 是 否 比 设备 上 的 数据 要 新 ， 反 之 亦 然 。 因 此 ， 我 们 必须 自己 提供 处 理 这 些 状 
况 的 算法 。 


清理 
在 数据 传输 的 尾声 ， 记 条 导 要 关闭 网 络 连 车 接 ， 清 除 除 临 时 文件 和 缓存 。 


Note : Sync Adapter 框架 会 在 一 个 后 台 线 程 中 执行 onPerformSync() 方法 ， 所 以 我 们 不 
需要 配置 后 台 处 理 任 务 。 


除了 和 同步 相关 的 任务 之 外 ， 我 们 还 应 该 尝试 将 一 些 周 期 性 的 网 络 相关 的 任务 合并 起 来 ， 并 
将 它们 添加 到 onPerformSync() 中 。 将 所 有 网 络 任务 集中 到 该 方法 内 处 理 ， 可 以 减少 由 启动 
和 停止 网 络 接口 所 造成 的 电量 损失 。 有 关 更 多 如 何在 进行 网 络 访问 时 更 高 效 地 使 用 电池 方面 
的 知识 ， 可 以 阅读 : Transferring Data Without Draining the Battery， 它 描述 了 一 些 在 数据 传 
输 代码 中 可 以 包含 的 网 络 访问 任务 


将 Sync Adapter 绑 定 到 框架 上 


现在 ， 我 们 已 经 将 数据 传输 代码 封装 在 Sync Adapter 组 件 中 ， 但 是 我 们 必须 让 框架 可 以 访问 
我 们 的 代码 。 为 了 做 到 这 一 点 ， 我 们 需要 创建 一 个 绑 定 Service， 它 将 一 个 特殊 的 Android 
Binder 对 象 从 Sync Adapter 组 件 传 递 给 框架 。 有 了 这 一 Binder 对 象 ， 框 架 就 可 以 调用 
onPerformSync() 方法 并 将 数据 传递 给 它 。 


在 服务 的 onCreate() 方法 中 将 我 们 的 Sync Adapter 组 件 实例 化 为 一 个 单 例 。 通 过 在 
onCreate() 方法 中 实例 化 该 组 件 ， 我 们 可 以 推迟 到 服务 启动 后 再 创建 它 ， 这 会 在 框架 第 一 次 
尝试 执行 数据 传输 时 发 生 。 我 们 需要 通过 一 种 线程 安全 的 方法 来 实例 化 组 件 ， 以 防止 Sync 


创建 Sync Adpater 


Adapter 框架 在 响应 触发 和 调度 时 ， 形 成 含有 多 个 Sync Adapter 执行 的 队列 。 


下 面 的 代码 片段 展示 了 我 们 应 该 如 何 实现 一 个 绑 定 Service 的 类 ， 实 例 化 我 们 的 Sync 
Adapter 组 件 ， 并 获取 Android Binder 对 象 : 


package com.example.android.syncadapter; 
Jee 
* Define a Service that returns an IBinder for the 
* sync adapter class, allowing the sync adapter framework to call 
* onPerformSync(). 
yf 
public class SyncService extends Service { 
// Storage for an instance of the sync adapter 
private static SyncAdapter sSyncAdapter = null; 
// Object to use as a thread-safe lock 
private static final Object sSyncAdapterLock = new Object(); 
/* 
* Instantiate the sync adapter object. 
vr 
@Override 
public void onCreate() { 
/* 
* Create the sync adapter as a singleton. 
* Set the sync adapter as syncable 
* Disallow parallel syncs 
ia 
synchronized (sSyncAdapterLock) { 
if (sSyncAdapter == null) { 
sSyncAdapter = new SyncAdapter(getApplicationContext(), true); 


} 
ps 
* Return an object that allows the system to invoke 
* the sync adapter. 
* 
i7 
@Override 
public IBinder onBind(Intent intent) { 
yee 
* Get the object that allows external processes 
* to call onPerformSync(). The object is created 
* in the base class code when the SyncAdapter 
* constructors call super() 
pA 
return sSyncAdapter.getSyncAdapterBinder(); 


Note : 要 看 更 多 Sync Adapter 绑 定 服务 的 例子 ， 可 以 阅读 样 例 代码 。 
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AS ho dE TR PT dS S RAP 


Sync Adapter 框架 需要 每 个 Sync Adapter 拥有 一 个 账户 类 型 。 在 创建 Stub 授权 器 章节 中 ， 
我 们 已 经 声明 了 账户 类 型 的 值 。 现 在 我 们 需要 在 Android 系统 中 配置 该 账户 类 型 。 要 配置 账 
户 类 型 ， 通 过 调用 addAccountExplicitly() 添加 一 个 使 用 其 账户 类 型 的 虚拟 账户 。 


调用 该 方法 最 合适 的 地 方 是 在 应 用 的 启动 Activity 的 onCreate() 方法 中 。 如 下 面 的 代码 样 例 
PD: 


public class MainActivity extends FragmentActivity { 


// Constants 

// The authority for the sync adapter's content provider 

public static final String AUTHORITY - "com.example.android.datasync.provider" 
// An account type, in the form of a domain name 

public static final String ACCOUNT TYPE - "example.com"; 

// The account name 

public static final String ACCOUNT - "dummyaccount"; 

// Instance fields 

Account mAccount; 


QOverride 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


// Create the dummy account 
mAccount - CreateSyncAccount(this); 


yis 
* Create a new dummy account for the sync adapter 
* 
* @param context The application context 
B 
public static Account CreateSyncAccount(Context context) { 
// Create the account type and default account 
Account newAccount - new Account( 
ACCOUNT, ACCOUNT TYPE); 
// Get an instance of the Android account manager 
AccountManager accountManager - 
(AccountManager) context.getSystemService( 
ACCOUNT SERVICE); 
A 
* Add the account and account type, no password or user data 
* If successful, return the Account object, otherwise report an error. 
2 
if (accountManager.addAccountExplicitly(newAccount, null, null))) { 
pies 


* If you don't set android:syncable-"true" in 

* in your «provider» element in the manifest, 

* then call context.setIsSyncable(account, AUTHORITY, 1) 

* here. 

*/ 

} else { 

yos 

* The account exists or some other error occurred. Log this, report it, 
* or handle it internally. 

v 


添加 Sync Adapter 的 元 数据 文件 


要 将 我 们 的 Sync Adapter 组 件 集 成 到 框架 中 ， 我 们 需要 向 框架 提供 描述 组 件 的 元 数据 ， 以 及 
额外 的 标识 信息 。 元 数据 指定 了 我 们 为 Sync Adapter 所 创建 的 账户 类 型 ， 声 明了 一 个 和 应 用 
相关 联 的 Content Provider Authority， 对 和 Sync Adapter 相关 的 一 部 分 系统 用 户 接口 进行 控 
制 ， 同 时 还 声明 了 其 它 同 步 相 关 的 标识 。 在 我 们 项 目的 /res/xml/ 目录 下 的 一 个 特定 文件 内 
声明 这 一 元 数据 ， 我 们 可 以 为 这 个 文件 命名 ， 不 过 通常 来 说 我 们 将 其 命名 为 

syncadapter.xml ° 
在 这 一 文件 中 包含 了 一 个 XML 标签 <sync-adapter> ， 它 包含 了 下 列 的 属性 字段 : 


android:contentAuthority 


Content Provider 的 URI Authority。 如 果 我 们 在 前 一 节 课 程 中 为 应 用 创建 了 一 个 Stub 
Content Provider， 那 么 请 使 用 在 manifest 清单 文件 中 添加 在 <provider> 标签 内 的 
android:authorities 属性 值 。 这 一 属性 的 更 多 细节 在 本 章 后 续 章 节 中 有 更 多 的 介绍 。 


如 果 我 们 正 使 用 Sync Adapter 将 数据 从 Content Provider 传输 到 服务 器 上 ， 该 属性 的 值 应 该 
和 数据 的 Content URI Authority 保持 一 致 。 这 个 值 也 是 我 们 在 manifest 清单 文件 中 添加 在 


«provider» 标签 内 android:authorities 属性 的 值 。 
android:accountType 


Sync Adapter 框架 所 需要 的 账户 类 型 。 这 个 值 必 须 和 我 们 所 创建 的 验证 器 元 数据 文件 内 所 提 
供 的 账户 类 型 一 致 (详细 内 容 可 以 阅读 : 创建 Stub 授权 器 ) 。 这 也 是 在 上 一 节 的 代码 片段 
中 。 常 量 AccouNT_ TYPE 的 值 。 


配置 相关 属性 


android:userVisible 


该 属性 设置 Sync Adapter 框架 的 账户 类 型 是 否 可 见 。 默 认 地 ， 和 账户 类 型 相关 联 的 账户 图 标 
和 标签 在 系统 设置 的 账户 选项 中 可 以 看 见 ， 所 以 我 们 应 该 将 Sync Adapter 设置 为 对 用 户 不 可 
A De be 
如 果 我 们 将 账户 类 型 设置 为 不 可 见 ， 那 么 我 们 仍然 可 以 允许 用 户 通过 一 个 Activity 中 的 用 户 接 
口 来 控制 Sync Adapter 。 


android:supportsUploading 


允许 我 们 将 数据 上 传 到 云 。 如 果 应 用 仅仅 下 载 数据 ， 那 么 请 将 该 属性 设置 为 false 。 


android:allowParallelSyncs 


允许 多 个 Sync Adapter 组 件 的 实例 同时 运行 。 如 果 应 用 支持 多 个 用 户 账户 并 且 我 们 希望 多 个 
用 户 并 行 地 传输 数据 ， 那 么 可 以 使 用 该 特性 。 如 果 我 们 从 不 执行 多 个 数据 传输 ， 那 么 这 个 选 
项 是 没 用 的 9 


android:isAlwaysSyncable 


指明 Sync Adapter 框架 可 以 在 任何 我 们 指定 的 时 间 运 行 Sync Adapter。 如 果 我 们 硕 望 通过 代 
" 来 控制 Sync Adapter 的 运行 时 机 ， 请 将 该 属性 设置 为 false 。 然 后 调用 requestSync() 来 

运行 Sync Adapter。 要 学 习 更 多 关于 运行 Sync Adapter 的 知识 ， 可 以 阅读 : 执行 Sync 
Adapter ° 


下 面 的 代码 展示 了 应 该 如 何 通过 XML 配置 一 个 使 用 单个 虚拟 账户 ， 并 且 只 执行 下 载 的 Sync 
Adapter : 


<?xml version="1.0" encoding="utf-8"?> 

<sync-adapter 
xmlns:android-"http://schemas.android.com/apk/res/android" 
android:contentAuthority-"com.example.android.datasync.provider" 
android:accountType="com.android.example.datasync" 
android: userVisible="false" 
android: supportsUploading="false" 
android:allowParallelSyncs="false" 
android: isAlwaysSyncable="true"/> 


在 Manifest 清单 文件 中 声明 Sync Adapter 


一 旦 我 们 将 Sync Adapter 组 件 集成 到 应 用 中 ， 我 们 需要 声明 相关 的 权限 来 使 用 它 ， 并 且 还 需 
要 声明 我 们 所 添加 的 绑 定 Service » 


由 于 Sync Adapter 组 件 会 运行 设备 网 络 之 间 传 输 数 据 的 代码 ， 所 以 我 们 需要 请 求 使 用 网 络 
的 权限 。 同 时 ， in 需要 读 写 Sync Adapter 配置 信息 的 权限 ， 这 样 我 们 才能 通过 应 
用 中 的 其 它 组 件 去 控制 Sync oe 。 另 外 ， 我 们 还 需要 一 个 特殊 的 权限 ， 来 允许 应 用 使 用 
我 们 在 创建 Stub 授权 器 中 所 创建 的 授权 器 组 件 。 


要 请 求 这 些 权 限 ， 将 下 列 内 容 添 加 到 应 用 manifest 清单 文件 中 ， 并 作为 ”<manifest> 标签 的 
子 标 签 : 


android.permission.INTERNET 


允许 Sync Adapter 访问 网 络 ， 使 得 它 可 以 从 设备 下 载 和 上 传 数据 到 服务 器 。 如 果 之 前 已 经 请 
求 了 该 权限 ， 那 么 就 不 需要 重复 请 求 了 。 


android.permission.READ SYNC SETTINGS 


允许 应 用 读 取 当前 的 Sync Adapter 配置 。 例 如 ， 我 们 需要 该 权限 来 调用 getlsSyncable() ° 


android.permission.WRITE SYNC SETTINGS 


允许 我 们 的 应 用 对 Sync Adapter 的 配置 进行 控制 。 我 们 需要 这 一 权限 来 通过 
addPeriodicSync() 方法 设置 执行 同步 的 时 间 间 隔 。 另 外 ， 调 用 requestSync() 方法 不 需要 用 
到 该 权限 。 更 多 信息 可 以 阅读 : 执行 Sync Adapter ° 


android.permission.AUTHENTICATE ACCOUNTS 
允许 我 们 使 用 在 创建 Stub 授权 器 中 所 创建 的 验证 器 组 件 。 


下 面 的 代码 片段 展示 了 如 何 添加 这 些 权限 : 


«manifest» 


«uses-permission 

android:name-"android.permission.INTERNET"/» 
«uses-permission 

android: name="android.permission.READ_SYNC_SETTINGS"/> 
<uses-permission 

android: name="android.permission.WRITE_SYNC_SETTINGS"/> 
<uses-permission 

android: name="android.permission.AUTHENTICATE_ACCOUNTS"/> 


</manifest> 


最 后 ， 要 声明 框架 用 来 和 Sync Adapter 进行 交互 的 绑 定 Service， 添 加 下 列 的 XML 代码 到 应 
用 manifest 清单 文件 中 ， 作 为 <application> 标签 的 子 标签 : 


«service 
android:name="com.example.android.datasync.SyncService" 
android:exported="true" 
android: process=":sync"> 

<intent-filter> 
«action android:name="android.content.SyncAdapter"/> 
</intent-filter> 
<meta-data android:name-"android.content.SyncAdapter" 
android: resource="@xml/syncadapter" /> 
</service> 


<intent-filter> 标签 配置 了 一 个 过 滤器 ， 它 会 被 带 有 android.content.SyncAdapter 这 一 
Action 的 Intent Pf A& X * 7X Intent 一 般 是 由 系统 为 了 运行 Sync Adapter 而 发 出 的 。 当 过 滤器 
被 触发 后 ， 系 统 会 尼 动 我 们 所 创建 的 绑 定 服务 ， 在 本 例 中 它 叫 做 syncservice 。 属 性 
android:exported="true" 允许 我 们 应 用 之 外 的 其 它 进程 (包括 系统 ) 访问 这 一 Service。 属 性 
android:process-":sync" 告诉 系统 应 该 在 一 个 全 局 共享 的 ， 且 名 字 叫 做 sync 的 进程 内 运行 
该 Service。 如 果 我 们 的 应 用 中 有 多 个 Sync Adapter， 那 么 它们 可 以 共享 该 进程 ， 这 有 助 于 减 
少 开销 。 


<meta-data> 标签 提供 了 我 们 之 前 为 Sync Adapter 所 创建 的 元 数据 XML 文件 的 文件 名 。 属 
性 android:name 指出 这 一 元 数据 是 针对 于 Sync Adapter 框架 的 。 而 android:resource 标签 
则 指定 了 元 数据 文件 的 名 称 。 


现在 我 们 已 经 为 Sync Adapter 准备 好 所 有 相关 的 组 件 了 。 下 一 节 课 将 讲授 如 何 让 Sync 


Adapter 框架 运行 Sync Adapter。 要 实现 这 一 点 ， 既 可 以 通过 响应 一 个 事件 的 方式 ， 也 可 以 
通过 执行 一 个 周期 性 任务 的 方式 。 


执行 Sync Adpater 


编写 :jdneo - 原文 :http://developer.android.com/training/sync-adapters/running-sync- 
adapter.html 


在 本 节 课 之 前 ， 我 们 已 经 学 习 了 如 何 创建 一 个 封装 了 数据 传输 代码 的 Sync Adapter 组 件 ， 以 
及 如 何 添加 其 它 的 组 件 ， 使 得 我 们 可 以 将 Sync Adapter 集成 到 系统 当中 。 现 在 我 们 已 经 拥有 
了 所 有 部 件 ， 来 安装 一 个 包含 有 Sync Adapter 的 应 用 了 ， 但 是 这 里 还 没有 任何 代码 是 负责 去 
运行 Sync Adapter。 


执行 Sync Adapter 的 时 机 ， 一 般 应 该 基于 某 个 计划 任务 或 者 一 些 事件 的 间接 结果 。 例 如 ， 我 
们 可 能 希望 Sync Adapter 以 一 个 定期 计划 任务 的 形式 运行 (比如 每 隔 一 段 时 间或 者 在 每 天 的 
一 个 国定 时 间 和 运行) 。 或 者 也 可 能 希望 当 设 备 上 的 数据 发 生变 化 后 ， 执 行 Sync Adapter » & 
们 应 该 避免 将 运行 Sync Adapter 作为 用 户 某 个 行为 的 直接 结果 ， 因 为 这 样 做 的 话 我 们 就 无 法 
利用 Sync Adapter 框架 可 以 按 计划 调度 的 特性 。 例 如 ， 我 们 应 该 在 Ul 中 避免 使 用 刷新 按 

钮 。 


下 列 情况 可 以 作为 运行 Sync Adapter 的 时 机 : 
当 服 务 端 数据 变更 时 : 


当 服 务 端 发 送 消息 告知 服务 端 数据 发 生变 化 时 ， 和 运行 Sync Adapter 以 响应 这 一 来 自 服务 端的 
消息 。 这 一 选项 允许 从 服务 器 更 新 数据 到 设备 上 ， 该 方法 可 以 避免 由 于 轮 询 服务 器 所 造成 的 
执行 效率 下 降 ， 或 者 电量 损耗 。 

当 设备 的 数据 变更 时 : 

当 设 备 上 的 数据 发 生变 化 时 ， 运 行 Sync Adapter。 这 一 选项 允许 我 们 将 修改 后 的 数据 从 设备 
发 送 给 服务 器 。 如 果 需 要 保证 服务 器 端 一 直 拥有 设备 上 最 新 的 数据 ， 那 么 这 一 选项 非常 有 
用 。 如 果 我 们 将 数据 存储 于 Content Provider， 那 么 这 一 选项 的 实现 将 会 非常 直接 。 如 果 使 用 
的 是 一 个 Stub Content Provider， 检 测 数据 的 变化 可 能 会 比较 困难 。 

当 和 系统 发 送 了 一 个 网 络 消息 : 

4 Android 系统 发 送 了 一 个 网 络 消息 来 保持 TCP/IP 连接 开启 时 ， 运 行 Sync Adapter。 这 个 
消息 是 网 络 框 架 (Networking Framework) 的 一 个 基本 部 分 。 可 以 将 这 一 选项 作为 自动 运行 
Sync Adapter 的 一 个 方法 。 另 外 还 可 以 考虑 将 它 和 基于 时 间 间 隔 运 行 Sync Adapter 的 策略 结 
合 起 来 使 用 。 

每 隔 一 定时 间 : 


可 以 每 隔 一 段 指定 的 时 间 间 隔 后 ， 和 运行 Sync Adapter， 或 者 在 每 天 的 固定 时 间 运 行 它 。 


根据 需求 : 


运行 Pi Adapter 以 响应 用 户 的 行为 。 然 而 ， 为 了 提供 最 佳 的 用 户 体验 ， 我 们 应 该 主要 依赖 
那些 更 加 自动 式 的 选项 。 使 用 自动 式 的 选项 ， 可 以 节省 大 量 的 电量 以 及 网 络 资源 。 


本 课程 的 后 续 部 分 会 详细 介绍 每 个 选项 。 


当 服 务 绒 数据 变化 时 ， 运 行 Sync Adapter 


如 果 我 们 的 应 用 从 服务 器 传输 数据 ， 且 服务 器 的 数据 会 频繁 地 发 生变 化 ， 那 么 可 以 使 用 一 个 
Syne Adapter 通过 下 载 数 据 来 响应 服务 端 数据 的 变化 。 要 运行 Sync Adapter， 我 们 需要 让 服 
务 端 向 应 用 的 BroadcastReceiver 发 送 一 条 特殊 的 消息 。 为 了 响应 这 条 消息 ， 可 以 调用 
ContentResolver.requestSync() 方法 ， 向 Sync Adapter 框架 发 出 信号 ， 让 它 运行 Sync 
Adapter ° 


谷歌 云 消息 (Google Cloud Messaging * GCM) 提供 了 我 们 TENRA 组 件 和 设备 端 组 
件 ， 来 让 上 述 消息 系统 能 够 运行 。 使 用 GCM 触发 数据 传输 比 通 过 向 服务 器 轮 询 的 方式 要 更 加 
可 靠 ， 也 更 加 有 效 。 因 为 轮 询 需 要 一 个 一 直 处 于 活跃 状态 的 Service， 而 GCM 使 用 的 
BroadcastReceiver 仅 在 消息 到 达 时 会 被 激活 。 另 外 ， 即 使 没有 更 新 的 内 容 ， 定 期 的 轮 询 也 会 
消耗 大 量 的 电池 电量 ， 而 GCM 仅 在 需要 时 才 会 发 出 消息 。 
Note : 如 果 我 们 使 用 GCM ， 将 广播 消息 发 送 到 所 有 安装 了 我 们 的 应 用 的 设备 ， 来 激活 
Sync gad 。 要 记 住 他 们 会 在 同一 时 间 (粗略 地 ) 收 到 我 们 的 消息 。 这 会 导致 在 同一 


iig dde 多 个 Sync Adapter 的 实例 在 运行 ， 进 而 导致 服务 器 和 网 络 的 负载 过 重 。 要 避免 
一 情况 ， ee 该 考虑 为 不 同 的 设备 设 定 不 同 的 Sync Adapter 来 延迟 启动 时 间 。 


下 面 的 代码 展示 了 如 何 通过 requestSync() 响应 一 个 接收 到 的 GCM 消息 : 


public class GcmBroadcastReceiver extends BroadcastReceiver { 


// Constants 

// Content provider authority 

public static final String AUTHORITY - "com.example.android.datasync.provider" 

// Account type 

public static final String ACCOUNT TYPE - "com.example.android.datasync"; 

// Account 

public static final String ACCOUNT - "default account"; 

// Incoming Intent key for extended data 

public static final String KEY SYNC REQUEST - 
"com.example.android.datasync.KEY SYNC REQUEST"; 


@Override 
public void onReceive(Context context, Intent intent) { 
// Get a GCM object instance 
GoogleCloudMessaging gcm = 
GoogleCloudMessaging.getInstance(context); 
// Get the type of GCM message 
String messageType = gcm.getMessageType(intent); 
/* 
* Test the message type and examine the message contents. 
* Since GCM is a general-purpose messaging system, you 
may receive normal messages that don't require a sync 
* adapter run. 
The following code tests for a a boolean flag indicating 


that the message is requesting a transfer from the device. 


* 
7] 
if (GoogleCloudMessaging.MESSAGE TYPE MESSAGE.equals(messageType) 
&& 
intent.getBooleanExtra(KEY SYNC REQUEST)) { 
Hes 


* Signal the framework to run your sync adapter. Assume that 
* app initialization has already created the account. 
5 

ContentResolver.requestSync(ACCOUNT, AUTHORITY, null); 


当 Content Provider 的 数据 变化 时 ， 运 行 Sync 
Adapter 


如 果 我 们 的 应 用 在 一 个 Content Provider 中 收集 数据 ， 并 且 硕 望 当 我 们 更 新 了 Content 
Provider 的 时 候 ， 同 时 更 新 服务 器 的 数据 ， 我 们 可 以 配置 Sync Adapter 来 让 它 自动 运行 。 要 
做 到 这 一 点 ， 首 先 应 该 为 Content Provider 注册 一 个 Observer ° 4 Content Provider 的 数据 
发 生 了 变化 之 后 ，Content Provider 框架 会 调用 Observer。 在 Observer 中 ， 调 用 
requestSync() 来 告诉 框架 现在 应 该 运行 Sync Adapter 了 。 


Note : 如 果 我 们 使 用 的 是 一 个 Stub Content Provider > R 4 # Content Provider 中 不 会 
有 任何 数据 ， 并 且 不 会 调用 onChange() 方法 。 在 这 种 情况 下 ， 我 们 不 得 不 提供 自己 的 
某 种 机 制 来 检测 设备 数据 的 变化 。 这 一 机 制 还 要 负责 在 数据 发 生变 化 时 调用 
requestSync() ° 


为 了 给 Content Provider 创建 一 个 Observer， 继 承 ContentObserver 类 ， 并 且 实 现 
onChange() 方法 的 两 种 形式 。 在 onChange() 中 ， 调 用 requestSync() 来 启动 Sync 
Adapter ° 


要 注册 Observer， 需 要 将 它 作为 参数 传递 给 registerContentObserver()。 在 该 方法 中 ， 我 们 
还 要 传递 一 个 我 们 想 要 监视 的 Content URI。Content Provider 框架 会 将 这 个 需要 监视 的 URI 
与 其 它 一 些 Content URIs 进行 比较 ， 这 些 其 它 的 Content URIs 来 自 于 ContentResolver 中 

那些 可 以 修改 Provider 的 方法 (如 ContentResolverinsert()) 所 传 入 的 参数 。 如 果 出 现 了 变 
化 ， 那 么 我 们 所 实现 的 ContentObserveronChange() 将 会 被 调用 。 


下 面 的 代码 片段 展示 了 如 何 定义 一 个 ContentObserver， 它 在 表 数 据 发 生变 化 后 调用 
requestSync() : 


public class MainActivity extends FragmentActivity { 


// Constants 

// Content provider scheme 

public static final String SCHEME - "content://"; 

// Content provider authority 

public static final String AUTHORITY - "com.example.android.datasync.provider"; 
// Path for the content provider table 

public static final String TABLE PATH - "data table"; 
// Account 

public static final String ACCOUNT - "default account"; 
// Global variables 

// A content URI for the content provider's data table 
Uri mUri; 

// A content resolver for accessing the provider 
ContentResolver mResolver; 


public class TableObserver extends ContentObserver { 
Hae 
* Define a method that's called when data in the 
* observed content provider changes. 
* This method signature is provided for compatibility with 
* older platforms. 
SA 


执行 Sync Adpater 


@Override 
public void onChange(boolean selfChange) { 
/* 
* Invoke the method signature available as of 
* Android platform version 4.1, with a null URI. 
wh 
onChange(selfChange, null); 
} 
/* 
* Define a method that's called when data in the 
* observed content provider changes. 
af 
@Override 
public void onChange(boolean selfChange, Uri changeUri) { 
/* 
* Ask the framework to run your sync adapter. 
* To maintain backward compatibility, assume that 
* changeUri is null. 
ContentResolver.requestSync(ACCOUNT, AUTHORITY, null); 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


// Get the content resolver object for your app 
mResolver - getContentResolver(); 
// Construct a URI that points to the content provider data table 
mUri - new Uri.Builder() 
. scheme ( SCHEME) 
.authority(AUTHORITY) 
.path(TABLE. PATH) 
.build(); 
/* 
* Create a content observer object. 
* Its code does not mutate the provider, so set 
* selfChange to "false" 
7d 
TableObserver observer - new TableObserver(false); 
/* 
* Register the observer for the data table. The table's path 
* and any of its subpaths trigger the observer. 
27 
mResolver.registerContentObserver(mUri, true, observer); 
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在 一 个 网 络 消息 之 后 ， 运 行 Sync Adapter 


当 可 以 获得 一 个 网 络 连接 时 ，Android 系统 会 每 隔 几 秒 发 送 RR TCP/IP 连接 处 于 
开局 状态 。 这 一 消息 也 会 传递 到 每 个 应 用 的 ContentResolver 。 通 过 调用 
setSyncAutomatically()， 我 们 可 以 在 ContentResolver 收 到 消息 后 ， 运 行 Sync Adapter ° 


每 当 网 络 消 息 被 发 送 后 运行 Sync Adapter， 通 过 这 样 的 调度 方式 可 以 保证 每 次 运行 Sync 
Adapter 时 都 可 以 访问 网 络 。 如 果 不 是 每 次 数据 变化 时 就 要 以 数据 传输 来 响应 ， 但 是 又 希望 自 
己 的 数据 会 被 定期 地 更 新 ， 那 么 odd ° m ， 如 果 我 们 不 想 要 定期 执行 
Sync Adapter， 但 希望 经 常 运行 它 ， 我 们 也 可 以 使 用 这 一 选项 。 


由 于 setSyncAutomatically() 方法 不 会 禁用 addPeriodicSync()， 所 以 Sync Adapter 可 能 会 在 
一 小 段 时 间 内 重复 地 被 触发 激活 。 如 果 我 们 想 要 定期 地 运行 Sync Adapter， 应 该 禁 
setSyncAutomatically() ° 


下 面 的 代码 片段 展示 如 何 配置 ContentResolver， 利 用 它 来 响应 网 络 消息 ， 从 而 运行 Sync 
Adapter : 
public class MainActivity extends FragmentActivity { 
// Constants 
// Content provider authority 
public static final String AUTHORITY - "com.example.android.datasync.provider"; 


// Account 

public static final String ACCOUNT - "default account"; 
// Global variables 

// A content resolver for accessing the provider 
ContentResolver mResolver; 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


// Get the content resolver for your app 

mResolver - getContentResolver(); 

// Turn on automatic syncing for the default account and authority 
mResolver.setSyncAutomatically(ACCOUNT, AUTHORITY, true); 


w 


定期 地 运行 Sync Adapter 


我 们 可 以 设置 一 个 在 运行 之 间 的 时 间 间 隔 来 定期 
运行 它 ， 还 可 以 两 种 策略 同时 使 用 。 定 期 地 运行 
保持 一 致 。 


明 运行 Sync Adapter ， 或 者 在 每 天 的 固定 时 间 
Sync Adapter 可 以 让 服务 器 的 更 新 闻 隔 大 致 


同样 地 ， 当 服务 器 ui Lid 空闲 时 ， 我 们 可 以 通过 在 夜间 定期 调用 Sync Adapter， 把 设 
备 上 的 数据 上 传 到 服务 器 。 大 多 数 用 户 在 晚上 不 会 关机 ， 并 为 手机 充电 ， 所 以 这 一 方法 是 可 
行 的 。 而 且 ， 通 常 来 说 ， 设 备 不 会 在 深夜 运行 除了 Sync Adapter 之 外 的 其 他 的 任务 。 , 
如 果 我 们 使 用 这 个 方法 的 话 ， 我 们 需要 注意 让 每 台 设 备 在 略微 不 同 的 时 间 触 发 数据 传输 。 
果 所 有 设备 在 同一 时 间 和 运行 我 们 的 Sync Adapter， 那 么 我 们 的 服务 器 和 移动 运营 商 的 网 P 
很 有 可 能 负载 过 重 。 


一 般 来 说 ， 当 我 们 的 用 户 不 需要 实时 更 新 ， 而 希望 定期 更 新 时 ， 使 用 定期 运行 的 策 咯 会 很 有 
用 。 如 果 我 们 希望 在 数据 的 实时 性 和 Sync Adapter 的 资源 消耗 之 间 进 行 一 个 平衡 ， 那 么 定期 
执行 是 一 个 不 错 的 选择 。 


要 定期 运行 我 们 的 Sync Adapter， 调 用 addPeriodicSync()。 这 样 每 隔 一 段 时 间 ，Sync 
Adapter 就 会 运行 。 由 于 Sync Adapter 框架 会 考虑 其 他 Sync Adapter 的 执行 ， 并 尝试 最 大 化 
电池 效率 ， 所 以 间隔 时 间 会 动态 地 进行 细微 调整 。 同 时 ， 如 果 当 前 无 法 获得 网 络 连 接 ， 框 架 
不 会 运行 我 们 的 Sync Adapter 。 


注意 ，addPeriodicSync() 方法 不 会 让 Sync Adapter 每 天 在 某 个 时 间 自 动 运行 。 要 让 我 们 的 
Sync Adapter 在 每 天 的 某 个 时 刻 自动 执行 ， 可 以 使 用 一 个 重复 计时 器 作为 触发 器 。 重 复 计 时 
器 的 更 多 细节 可 以 阅读 : AlarmManager。 如 果 我 们 使 用 setlnexactRepeating() 方法 设置 了 一 
个 每 天 的 触发 时 刻 会 有 粗略 变化 的 触发 器 ， 我 们 仍然 应 该 将 不 同 设备 Sync Adapter 的 运行 时 
间 随 机 化 ， 使 得 它们 的 执行 交错 开 来 。 


addPeriodicSync() 方法 不 会 禁用 setSyncAutomatically()， 所 以 我 们 可 能 会 在 一 小 段 时 间 内 产 
生 多 个 Sync Adapter 的 运行 实例 。 另 外 ， 仅 有 一 部 分 Sync Adapter 的 控制 标识 可 以 在 调用 
addPeriodicSync() 时 使 用 。 不 被 允许 的 标识 在 该 方法 的 文档 中 可 以 查看 。 


下 面 的 代码 样 例 展 示 了 如 何 定期 执行 Sync Adapter : 


public class MainActivity extends FragmentActivity { 


// Constants 
// Content provider authority 
public static final String AUTHORITY - "com.example.android.datasync.provider"; 
// Account 
public static final String ACCOUNT - "default account"; 
// Sync interval constants 
public static final long SECONDS PER MINUTE - 60L; 
public static final long SYNC INTERVAL IN MINUTES = 60L; 
public static final long SYNC INTERVAL - 

SYNC INTERVAL IN MINUTES * 

SECONDS PER MINUTE; 
// Global variables 
// A content resolver for accessing the provider 
ContentResolver mResolver; 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState) ; 


// Get the content resolver for your app 
mResolver = getContentResolver(); 
/* 
* Turn on periodic syncing 
E 
ContentResolver.addPeriodicSync( 
ACCOUNT, 
AUTHORITY, 
Bundle.EMPTY, 
SYNC INTERVAL); 


按 需 求 执 行 Sync Adapter 


以 响应 用 户 请 求 的 方式 运行 Sync Adapter 是 最 不 推荐 的 策略 。 要 知道 ， 该 框架 是 被 特别 设计 
的 ， 它 可 以 让 Sync Adapter 在 根据 某 个 调度 规则 运行 时 ， 能 够 尽量 最 高 效 地 使 用 手机 电量 。 
显然 ， 在 数据 改变 的 时 候 执行 同步 可 以 更 有 效 的 使 用 手机 电量 ， 因 为 电量 都 消耗 在 了 更 新 新 

的 数据 上 。 


相 比 之 下 ， 人 允许 用 户 按照 自己 的 需求 运行 Sync Adapter 意味 着 Sync Adapter 会 自己 运行 ， 
这 将 无 法 有 效 地 使 用 电量 和 网 络 资源 。 如 果 根 据 需 求 执行 同步 ， 会 诱导 用 户 即 便 没 有 证 据 表 
明 数 据 发 生 了 变化 也 请 求 一 个 更 新 ， 这 些 无 用 的 更 新 会 导致 对 电量 的 低 效 率 使 用 。 一 般 来 


说 ， 我 们 的 应 用 应 该 使 用 其 它 信 号 来 触发 一 个 同步 更 新 或 者 让 它们 定期 地 去 执行 ， 而 不 是 依 
BT ALP HRA © 


不 过 ， 如 果 我 们 仍然 想 要 按照 需求 运行 Sync Adapter， 可 以 将 Sync Adapter 的 配置 标识 设置 
为 手动 执行 ， 之 后 调用 ContentResolver.requestSync() 来 触发 一 次 更 新 。 


通过 下 列 标识 来 执行 按 需求 的 数据 传输 : 
SYNC_EXTRAS_MANUAL 


强制 执行 手动 的 同步 更 新 。Sync Adapter 框架 会 忽略 当前 的 设置 ， 比 如 通 
setSyncAutomatically() 方法 设置 的 标识 。 


位 


SYNC EXTRAS. EXPEDITED 


强制 同步 立即 执行 。 如 果 我 们 不 设置 此 项 ， 系 统 可 能 会 在 运行 同步 请 求 之 前 等 待 一 小 段 时 
间 ， 因 为 它 会 尝试 将 一 小 段 时 间 内 的 多 个 请 求 集中 在 一 起 调度 ， 目 的 是 为 了 优化 电量 的 使 
用 。 


下 面 的 代码 片段 将 展示 如 何 调用 requestSync() 来 响应 一 个 按钮 点 击 事件 : 


执行 Sync Adpater 


public class MainActivity extends FragmentActivity { 


// Constants 

// Content provider authority 

public static final String AUTHORITY - 
"com.example.android.datasync.provider" 

// Account type 

public static final String ACCOUNT TYPE - "com.example.android.datasync"; 

// Account 

public static final String ACCOUNT - "default account"; 

// Instance fields 

Account mAccount; 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


yes 
* Create the dummy account. The code for CreateSyncAccount 
* is listed in the lesson Creating a Sync Adapter 
w 


mAccount = CreateSyncAccount(this); 


* Respond to a button click by calling requestSync(). This is an 
* asynchronous operation. 


* This method is attached to the refresh button in the layout 
* XML file 


* @param v The View associated with the method call, 
* in this case a Button 
E 

public void onRefreshButtonClick(View v) { 


// Pass the settings flags by inserting them in a bundle 
Bundle settingsBundle - new Bundle(); 
settingsBundle.putBoolean( 
ContentResolver.SYNC EXTRAS MANUAL, true); 
settingsBundle.putBoolean( 
ContentResolver.SYNC EXTRAS EXPEDITED, true); 
/* 
* Request the sync for the default account, authority, and 
* manual sync settings 
22 
ContentResolver.requestSync(mAccount, AUTHORITY, settingsBundle); 


404 


执行 Sync Adpater 


405 


使 用 Volley 传输 网 络 数据 


编写 :kesenhoo - 原文 :http://developer.android.com/training/volley/index.html 


volley 是 一 个 HTTP 库 ， 它 能 够 帮助 Android app 更 方便 地 执行 网 络 操作 ， 最 重要 的 是 ， 
它 更 快速 高 效 。 我 们 可 以 通过 开源 的 AOSP 仓库 获取 到 Volley 。 


YOU SHOULD ALSO SEE 


使 用 Volley 来 编写 一 个 app， 请 参考 2013 Google I/O schedule app。 另 外 需要 特别 关注 下 面 


2 个 部 分 : 


e ImageLoader 
e BitmapCache 


VIDEO - Volley: Easy,Fast Networking for Android 


Volley 有 如 下 的 优点 : 


e 自动 调度 网 络 请 求 。 

。 高 并 发 网 络 连接 。 

e 通过 标准 的 HTTP cache coherence (高 速 缓存 一 致 性 ) 缓存 磁盘 和 内 存 透 明 的 响应 。 

e 支持 指定 请 求 的 优先 级 。 

e 撤销 请 求 API。 我 们 可 以 取消 单个 请 求 ， 或 者 指定 取消 请 求 队 列 中 的 一 个 区 域 。 

e 框架 容易 被 定制 ， 例 如 ， 定 制 重 试 或 者 回 退 功能 。 

e 强大 的 指令 (Strong ordering) 可 以 使 得 异步 加 载 网 络 数据 并 正确 地 显示 到 UI 的 操作 更 

加 简单 。 

e 包含 了 调试 与 追踪 工具 。 
Volley 擅长 执行 用 来 显示 UI 的 RPC 类 型 操作 ， 例 如 获取 搜索 结果 的 数据 。 它 轻松 的 整合 了 
任何 协议 ， 并 输出 操作 结果 的 数据 ， 可 以 是 原始 的 字符 串 ， 也 可 以 是 图 片 ， 或 者 是 JSON ° 
通过 提供 内 置 的 我 们 可 能 使 用 到 的 功能 ，Volley 可 以 使 得 我 们 免 去 重复 编写 样板 代码 ， 使 我 
们 可 以 把 关注 点 放 在 app 的 功能 逻辑 上 。 


Volley 不 适合 用 来 下 载 大 的 数据 文件 。 因 为 Volley 会 保持 在 解析 的 过 程 中 所 有 的 响应 。 对 于 
下 载 大 量 的 数据 操作 ， 请 考虑 使 用 DownloadManager ° 


Volley 框架 的 核心 代码 是 托管 在 AOSP 仓库 的 frameworks/volley 中 ， 相 关 的 工具 放 在 
toolbox 下 。 把 Volley 添加 到 项 目 中 最 简便 的 方法 是 Clone 仓库 ， 然 后 把 它 设置 为 一 个 
library project : 


1. 通过 下 面 的 命令 来 Clone 仓 库 : 


git clone https://android.googlesource.com/platform/frameworks/volley 


2. V4—^* Android library project 的 方式 导入 下 载 的 源 代码 到 你 的 项 目 中 。( 如 果 你 使 用 
Eclipse， 请 参考 Managing Projects from Eclipse with ADT， 或 者 编译 成 一 个 jar X 
件 。 


Lessons 


发 送 一 个 简单 的 网 络 请 求 (Sending a Simple Request) 
学 习 如 何 通过 Volley 默认 的 行为 发 送 一 个 简单 的 请 求 ， 以 及 如 何 取消 一 个 请 求 。 
建立 一 个 请 求 队列 (Setting Up a RequestQueue) 


学 习 如 何 建立 一 个 请 求 队列 〈 RequestQueue ) ， 以 及 如 何 实现 一 个 单 例 模 式 来 创建 一 个 请 求 
队列 ， 使 RequestQueue 能 够 持续 保持 在 我 们 app 的 生命 周期 中 。 


生成 一 个 标准 的 请 求 (Making a Standard Request) 


学 习 如 何 使 用 Volley 的 out-of-the-box (可 直接 使 用 、 无 需 配 置 ) 请 求 类 型 (原始 字符 串 、 图 
片 和 JSON) 来 发 送 一 个 请 求 。 


实现 自 定 义 的 请 求 (Implementing a Custom Request) 


学 习 如 何 实 现 一 个 自 定义 的 请 求 。 


发 送 简单 的 网 络 请 求 


编写 :kesenhoo - 原文 :http://developer.android.com/training/volley/simple.html 


使 用 Volley 的 方式 是 i 创建 一 个 RequestQueue 并 传递 Request 对 REE ° RequestQueue 
管理 用 来 执行 网 络 操作 的 工作 线程 ， 从 缓存 中 读 取 数 据 ， 写 数据 到 缓存 ， 并 解析 Http 的 响应 
内 容 。 请 求解 析 原 始 的 响应 数据 ，Volley 会 把 解析 完 的 响应 数据 分 发 给 主线 程 。 


这 节 课 会 介绍 如 何 使 用 volley.newRequestQueue 这 个 便捷 的 方法 (建立 一 个 请 求 队列 
RequestQueue ) 来 发 送 一 个 请 求 。 在 下 一 节 课 建立 一 个 RequestQueue 中 ， 会 介绍 如 何 自己 


建立 一 个 RequestQueue ? 


这 节 课 也 会 介绍 如 何 添加 一 个 请 求 到 Requesutqueue 以 及 如 何 取消 一 个 请 求 。 


1)Add the INTERNET Permission 


为 了 使 用 Volley， 你 必须 添加 android.permission.INTERNET 权限 到 你 的 manifest 文 件 中 。 没 有 
这 个 权限 ， 你 的 app 将 无 法 访问 网 络 。 


2)Use newRequestQueue 


Volley 提 供 了 一 个 简便 的 方法 : volley.newRequestQueue 用 来 为 你 建立 一 个 RequestQueue ， 使 
用 默认 值 ， 并 局 动 这 个 队列 。 例 如 : 


final TextView mTextView = (TextView) findViewById(R.id.text); 


// Instantiate the RequestQueue. 
RequestQueue queue - Volley.newRequestQueue(this); 
String url ="http://www.google.com"; 


// Request a string response from the provided URL. 
StringRequest stringRequest - new StringRequest(Request.Method.GET, url, 
new Response.Listener() { 
QOverride 
public void onResponse(String response) { 
// Display the first 500 characters of the response string. 
mTextView.setText("Response is: "+ response.substring(0,500)); 


} 


}, new Response.ErrorListener() { 
@Override 
public void onErrorResponse(VolleyError error) { 
mTextView.setText("That didn't work!"); 


} 
3; 
// Add the request to the RequestQueue. 
queue.add(stringRequest); 


Volley 总 是 将 解析 后 的 数据 返回 至 主线 程 中 。 在 主线 程 中 更 加 合适 使 用 接收 到 的 数据 用 来 操作 
UI 控 件 ， 这 样 你 可 以 在 响应 的 handler 中 轻松 的 修改 Ul， 但 是 对 于 库 提 供 的 一 些 其 他 方法 是 有 
些 特殊 的 ， 例 如 与 取消 有 关 的 。 


关于 如 何 创 建 你 自己 的 请 求 队列 ， 而 不 是 使 用 Volley.newRequestQueue 方 法 ， 请 查看 建立 一 
个 请 求 队列 Setting Up a RequestQueue。 


3)Send a Request 


为 了 发 送 一 个 请 求 ， 你 只 需要 构造 一 个 请 求 并 通过 add() 方法 添加 到 RequestQueue P o — E 
你 添加 了 这 个 请 求 ， 它 会 通过 队列 ， 得 到 处 理 ， 然 后 得 到 原始 的 响应 数据 并 返 


当 你 执行 add() 方法 时 ，Volley 触 发 执行 一 个 缓存 处 理 线程 以 及 一 系列 网 络 处 理 线程 。 当 你 添 
加 一 个 请 求 到 队列 中 ， 它 将 被 缓存 线程 所 捕获 并 触发 : 如 果 这 个 请 求 可 以 被 缓存 处 理 ， 那 么 
会 在 缓存 线程 中 执行 响应 数据 的 解析 并 返回 到 主线 程 。 如 果 请 求 不 能 被 缓存 所 处 理 ， 它 会 被 
放 到 网 络 队列 中 。 网 络 线程 池 中 的 第 一 个 可 用 的 网 络 线程 会 从 队列 中 获取 到 这 个 请 求 并 执行 
HTTP 操 作 ， 解 析 工 作 线 程 的 响应 数据 ， 把 数据 写 到 缓存 中 并 把 解析 之 后 的 数据 返回 到 主线 
程 。 


请 注意 那些 比较 耗 时 的 操作 ， 例 如 MO 与 解析 parsing/decoding 都 是 执行 在 工作 线程 。 你 可 以 
在 任何 线程 中 添加 一 个 请 求 ， 但 是 响应 结果 都 是 返回 到 主线 程 的 。 


下 图 1， 演 示 了 一 个 请 求 的 生命 周期 : 





4)Cancel a Request 


对 请 求 Request 对 象 调用 cance1() 方法 取消 一 个 请 求 。 一 旦 取消 ，Volley 会 确保 你 的 响应 
Handler 不 会 被 执行 。 这 意味 着 在 实际 操作 中 你 可 以 在 activity 的 onstop() 方法 中 取消 所 有 
pending 在 队列 中 的 请 求 。 你 不 需要 通过 检测 getActivity() == null 来 丢弃 你 的 响应 
handler， 其 他 类 似 onSaveInstanceState() 等 保护 性 的 方法 里 面 也 都 不 需要 检测 。 


为 了 利用 这 种 优势 ， 你 应 该 跟踪 所 有 已 经 发 送 的 请 求 ， 以 便 在 需要 的 时 候 可 以 取消 他 们 。 有 
一 个 简便 的 方法 : 你 可 以 为 每 一 个 请 求 对 象 都 绑 定 一 个 tag 对 象 。 然 后 你 可 以 使 用 这 个 tag 来 提 
供 取消 的 范围 。 例 如 ， 你 可 以 为 你 的 所 有 请 求 都 绑 定 到 执行 的 Activity 上 ， 然 后 你 可 以 

在 onStop() 方法 执行 requestQueue.cancelAll(this) ° 同样 的 ， 你 可 以 为 ViewPager 中 的 所 
有 请 求 缩 略图 Request 对 象 分 别 打 上 对 应 Tab 的 tag。 并 在 滑动 时 取消 这 些 请 求 ， 用 来 确保 新 生 
成 的 tab 不 会 被 前 面 tab 的 请 求 任务 所 卡 到 。 


下 面 一 个 使 用 String 来 打 Tag 的 例子 : 


1. 定义 你 的 tag 并 添加 到 你 的 请 求 任务 中 。 


public static final String TAG = "MyTag"; 
StringRequest stringRequest; // Assume this exists. 
RequestQueue mRequestQueue; // Assume this exists. 


// Set the tag on the request. 
stringRequest.setTag(TAG); 


// Add the request to the RequestQueue. 
mRequestQueue.add(stringRequest); 


1. 在 activity 的 onStop() 方 法 里 面 ， 取 消 所 有 的 包含 这 个 tag 的 请 求 任务 。 


@Override 
protected void onStop () { 
super.onStop(); 
if (mRequestQueue != null) { 
mRequestQueue.cancelAll( TAG) ; 


当 取 消 请 求 时 请 注意 : 如 果 你 依赖 你 的 响应 handler 来 标记 状态 或 者 触发 另外 一 个 进程 
要 对 此 进行 考虑 。 再 说 一 次 ，response handler 是 不 会 被 执行 的 。 


建立 请 求 队列 (RequestQueue) 


编写 :kesenhoo - 原文 :http://developer.android.com/training/volley/requestqueue.html 


前 一 节 课 演示 了 如 何 使 用 volley.newRequestQueue 这 一 简便 的 方法 来 建立 一 
个 RequestQueue ， 这 是 利用 了 Volley 默认 行为 的 优势 。 这 节 课 会 介绍 如 何 显 式 地 建立 一 个 
RequestQueue ， 以 便 满足 我 们 自 定 义 的 需求 。 


这 节 课 同样 会 介绍 一 种 推荐 的 实现 方式 : 创建 一 个 单 例 的 RequestQueue ， 这 使 得 
RequestQueue 能 够 持续 保持 在 我 们 app 的 生命 周期 中 。 


建立 网 络 和 缓存 


一 个 RequestQueue 需要 两 部 分 来 支持 它 的 工作 : 一 部 分 是 网 络 操作 à 用 来 传输 请 求 另外 一 
个 是 用 来 处 理 缓存 操作 的 Cache。 在 Volley 的 工具 箱 中 包含 了 标准 的 实现 方 

式 DiskBasedcache 提供 了 每 个 文件 与 对 应 响应 数据 一 一 映射 的 缓存 实现 。 BasicNetwork 
提供 了 一 个 基于 AndroidHttpClient 或 者 HttpURLConnection 的 网 络 传输 。 


BasicNetwork 是 Volley 默认 的 网 络 操作 实现 方式 。 一 个 Basicnetwork 必须 使 用 我 们 的 app 
用 于 连接 网 络 的 HTTP Client 进行 初始 化 。 这 个 Client 通常 是 AndroidHttpClient 或 者 
HttpURL Connection : 


e 对 于 app target API level 4& T. API 9 (Gingerbread) 的 使 用 AndroidHttpClient » # 
Gingerbread 2 Àf > HttpURL Connection 是 不 可 靠 的 。 对 于 这 个 的 细节 ， 请 参考 
Android's HTTP Clients ° 

e 对 于 API Level 9 以 及 以 上 的 ， 使 用 HttpURL Connection 。 


我 们 可 以 通过 检查 系统 版 本 选择 合适 的 HTTP Client， 从 而 创建 一 个 能 够 运行 在 所 有 Android 
版 本 上 的 应 用 。 例 如 : 


HttpStack stack; 


// If the device is running a version >= Gingerbread... 

if (Build.VERSION.SDK INT >= Build.VERSION CODES.GINGERBREAD) { 
// ...use HttpURLConnection for stack. 

} else { 
// ...use AndroidHttpClient for stack. 


} 


Network network = new BasicNetwork(stack); 


下 面 的 代码 片段 演示 了 如 何 一 步 步 建立 一 个 RequestQueue : 


RequestQueue mRequestQueue; 


// Instantiate the cache 
Cache cache = new DiskBasedCache(getCacheDir(), 1024 * 1024); // 1MB cap 


// Set up the network to use HttpURLConnection as the HTTP client. 
Network network - new BasicNetwork(new HurlStack()); 


// Instantiate the RequestQueue with the cache and network. 
mRequestQueue - new RequestQueue(cache, network); 


// Start the queue 
mRequestQueue.start(); 


String url ="http://www.myurl.com"; 


// Formulate the request and handle the response. 
StringRequest stringRequest - new StringRequest(Request.Method.GET, url, 
new Response.Listener<String>() { 
@Override 
public void onResponse(String response) { 
// Do something with the response 


} 
}, 
new Response.ErrorListener() { 
@Override 
public void onErrorResponse(VolleyError error) { 
// Handle error 
} 
H); 


// Add the request to the RequestQueue. 
mRequestQueue.add(stringRequest ); 


如 果 我 们 仅仅 是 想 做 一 个 单 次 的 请 求 并 且 不 想 要 线程 池 一 直 保留 ， 我 们 可 以 通过 使 用 在 前 面 
一 课 : 发 送 一 个 简单 的 请 求 (Sending a Simple Request) 文章 中 提 到 的 
Volley.newRequestQueue() 方法 ， 在 任何 需要 的 时 刻 创 建 RequestQueue ， 然 后 在 我 们 的 响应 
回调 里 面 执行 stop 方法 来 停止 操作 。 但 是 更 通常 的 做 法 是 创建 一 个 RequestQueue 并 设 
置 为 一 个 单 例 。 下 面部 分 将 演示 这 种 做 法 。 


使 用 单 例 模式 


如 果 我 们 的 应 用 需要 持续 地 使 用 网 络 ， 更 加 高 效 的 方式 应 该 是 建立 一 个 RequestQueue 的 单 
例 ， 这 样 它 能 够 持续 保持 在 整个 app 的 生命 周期 中 。 我 们 可 以 通过 多 种 方式 来 实现 这 个 单 
例 。 推 荐 的 方式 是 实现 一 个 单 例 类 ， 里 面 封装 了 RequestQueue 对 象 与 其 它 的 Volley 功能 。 


另外 一 个 方法 是 继承 Application 类 ， 并 在 Application.OnCreate() 方法 里 面 建立 
RequestQueue 。 但 是 我 们 并 不 推荐 这 个 方法 ， 因 为 一 个 static 的 单 例 能 够 以 一 种 更 加 模块 化 
的 方式 提供 同样 的 功能 。 


一 个 关键 的 概念 是 RequestQueue 必须 使 用 Application context 来 实例 化 ， 而 不 是 Activity 
context。 这 确保 了 RequestQueue ERM app 的 生命 周期 中 一 直 存 活 ， 而 不 会 因为 activity 的 
重新 创建 而 被 重新 创建 (例如 ， 当 用 户 旋 转 设备 时 )。 


下 面 是 一 个 单 例 类 ， 提 供 了 RequestQueue 与 ImageLoader 功能 : 


public class MySingleton { 
private static MySingleton mInstance; 
private RequestQueue mRequestQueue; 
private ImageLoader mImageLoader; 
private static Context mCtx; 


private MySingleton(Context context) { 
mCtx - context; 
mRequestQueue - getRequestQueue(); 


mImageLoader = new ImageLoader(mRequestQueue, 
new ImageLoader.ImageCache() { 
private final LruCache<String, Bitmap» 
cache = new LruCache<String, Bitmap>(20); 


@Override 
public Bitmap getBitmap(String url) { 
return cache.get(url); 


@Override 
public void putBitmap(String url, Bitmap bitmap) { 
cache.put(url, bitmap); 


3); 


public static synchronized MySingleton getInstance(Context context) { 
if (mInstance == null) { 
mInstance - new MySingleton(context); 


} 


return mInstance; 


public RequestQueue getRequestQueue() { 
if (mRequestQueue == null) { 
// getApplicationContext() is key, it keeps you from leaking the 
// Activity or BroadcastReceiver if someone passes one in. 
mRequestQueue - Volley.newRequestQueue(mCtx.getApplicationContext()); 


} 


return mRequestQueue; 


public «T» void addToRequestQueue(Request<T> req) { 
getRequestQueue( ).add(req); 


public ImageLoader getImageLoader() { 
return mImageLoader; 


下 面 演示 了 利用 单 例 类 来 执行 RequestQueue 的 操作 : 


// Get a RequestQueue 
RequestQueue queue - MySingleton.getInstance(this.getApplicationContext()). 
getRequestQueue(); 


// Add a request (in this example, called stringRequest) to your RequestQueue. 
MySingleton.getInstance(this).addToRequestQueue(stringRequest); 


创 


建 标准 的 网 络 请 求 


编写 :kesenhoo - 原文 :http://developer.android.com/training/volley/request.html 


这 一 课 会 介绍 如 何 使 用 Volley 支持 的 常用 请 求 类 型 : 


StringRequest ° 指定 一 个 URL 并 在 响应 回调 中 接收 一 个 原始 的 字符 串 数 据 2 请 参考 前 
一 课 的 示例 。 

ImageRequest 。 指 定 一 个 URL 并 在 响应 回调 中 接收 一 个 图 片 。 

JsonObjectRequest 与 JsonArrayRequest ( 均 为 JsonRequest 的 子 类 ) i 指定 一 个 URL 
并 在 响应 回调 中 获取 到 一 个 JSON 对 象 或 者 JSON 数组 。 


如 果 我 们 需要 的 是 上 面 演示 的 请 求 类 型 ， 那 么 我 们 很 可 能 不 需要 实现 一 个 自 定义 的 请 求 。 这 
节 课 会 演示 如 何 使 用 那些 标准 的 请 求 类 型 。 关 于 如 何 实现 自 定义 的 请 求 ， 请 看 下 一 课 : 实现 
自 定义 的 请 求 。 


请 


求 一 张 图 上 


Volley 为 请 求 图 片 提供 了 如 下 的 类 。 这 些 类 依次 有 着 依赖 关系 ， 用 来 支持 在 不 同 的 层级 进行 
图 片 处 理 : 


ImageRequest 一 一 一 个 封装 好 的 ， 用 来 处 理 URL. 请 求 图 片 并 且 返 回 一 张 解 完 码 的 位 图 
(bitmap) 。 它 同样 提供 了 一 些 简 便 的 接口 方法 ， 例 如 指定 一 个 大 小 进行 重新 裁剪 。 它 
的 主要 好 处 是 Volley 会 确保 类 似 decode，resize 等 耗 时 的 操作 在 工作 线程 中 执行 。 





ImageLoader 一 个 用 来 处 理 加 载 与 缓存 从 网 络 上 获取 到 的 图 片 的 帮助 
类 。 ImageLoader 是 大 量 ImageRequest 的 协调 器 。 例 如 ， 在 Listview 中 需要 显示 大 
量 缩 略 图 的 时 候 。 ImageLoader 为 通常 的 Volley cache 提供 了 更 加 前 瞪 的 内 存 缓存 ， 这 
个 缓存 对 于 防止 图 片 拌 动 非常 有 用 。 这 还 使 得 在 不 阻塞 或 者 延迟 主线 程 的 前 提 下 实现 组 
存 命 中 (这 对 于 使 用 磁盘 VO 是 无 法 实现 的 ) © ImageLoader 还 能 够 实现 响应 联合 
(response coalescing) ， 避 免 几乎 每 一 个 响应 回调 里 面 都 设置 bitmap 到 view 上 面 。 
响应 联合 使 得 能 够 同时 提交 多 个 响应 ， 这 提升 了 性 能 。 

NetworkImageView 在 ImageLoader 的 基础 上 建立 ， 并 且 在 通过 网 络 URL. 取 回 的 图 
片 的 情况 下 ， 有 效 地 替换 Imageview 。 如 果 view 从 层次 结构 中 分 离 ， NetworkrmageView 
也 可 以 管理 取消 挂 起 请 求 。 





使 用 ImageRequest 


下 面 是 一 个 使 用 ImageRequest 的 示例 。 它 会 获取 URL 上 指定 的 图 片 并 显示 到 app 上 。 注意 
到 ， 里 面 演示 的 RequestQueue 是 通过 上 一 课 提 到 的 单 例 类 实现 的 : 


ImageView mImageView; 
String url - "http://i.imgur.com/7spzG.png"; 
mImageView = (ImageView) findViewById(R.id.myImage); 


// Retrieves an image specified by the URL, displays it in the UI. 
ImageRequest request - new ImageRequest(url, 
new Response.Listener() { 
@Override 
public void onResponse(Bitmap bitmap) { 
mImageView.setImageBitmap(bitmap); 
} 
Jey (ei eke mui, 
new Response.ErrorListener() { 
public void onErrorResponse(VolleyError error) { 
mImageView.setImageResource(R.drawable.image load error); 


3); 


// Access the RequestQueue through your singleton class. 
MySingleton.getInstance( this) .addToRequestQueue( request ); 


使 用 ImageLoader 和 NetworklmageView 


我 们 可 以 使 用 ImageLoader 与 NetworkImageView 来 有 效 地 管理 类 似 ListView 等 显示 多 张 图 
片 的 情况 。 在 layout XML 文件 中 ， 我 们 以 与 使 用 ImageView 差不多 的 方法 使 用 


NetworkImageView ， 例 如 : 


«com.android.volley.toolbox.NetworkImageView 
android: id="@+id/networkImageView" 
android: layout_width="150dp" 
android: layout_height="170dp" 
android: layout_centerHorizontal="true" /> 


我 们 可 以 使 用 ImageLoader 自身 来 显示 一 张 图 片 ， 例 如 : 


ImageLoader mImageLoader; 

ImageView mImageView; 

// The URL for the image that is being loaded. 

private static final String IMAGE URL - 
"http://developer.android.com/images/training/system-ui.png"; 


mImageView = (ImageView) findViewById(R.id.regularImageView) ; 


// Get the ImageLoader through your singleton class. 

mImageLoader = MySingleton.getInstance(this).getlImageLoader(); 

mImageLoader.get(IMAGE URL, ImageLoader.getImageListener(mImageView, 
R.drawable.def image, R.drawable.err image)); 


然而 ， 如 果 我 们 要 做 的 是 为 ”Imageview 进行 图 片 设 置 ， 那 么 我 们 可 以 使 用 NetworkImageview 
来 实现 ， 例 如 : 


ImageLoader mImageLoader; 

NetworkImageView mNetworkImageView; 

private static final String IMAGE URL - 
"http://developer.android.com/images/training/system-ui.png"; 


// Get the NetworkImageView that will display the image. 
mNetworkImageView - (NetworkImageView) findViewById(R.id.networkImageView); 


// Get the ImageLoader through your singleton class. 
mImageLoader = MySingleton.getInstance(this).getlImageLoader(); 


// Set the URL of the image that should be loaded into this view, and 
// specify the ImageLoader that will be used to make the request. 
mNetworkImageView.setImageUrl(IMAGE URL, mImageLoader); 


上 面 的 代码 是 通过 通过 前 一 节 课 讲 到 的 单 例 类 来 访问 RequestQueue “J ImageLoader ° 这 种 
方法 保证 了 我 们 的 app 创建 这 些 类 的 单 例会 持续 存在 于 app 的 生命 周期 。 这 对 于 

ImageLoader 《一 个 用 来 处 理 加 载 与 缓存 图 片 的 帮助 类 ) 很 重要 的 原因 是 : 内 存 缓存 的 主要 功 
能 是 允许 非 持 动 旋转 。 使 用 单 例 模式 可 以 使 得 bitmap 的 缓存 比 activity 存在 的 时 间 长 。 如 果 
RAT activity 中 创建 ImageLoader ， 这 个 ImageLoader 有 可 能 会 在 每 次 旋转 设备 的 时 候 都 
被 重新 创建 。 这 可 能 会 导致 抖动 。 


举 一 个 LRU cache 的 例子 


Volley 工具 箱 中 提供 了 一 种 通过 DiskBasedcache 类 实现 的 标准 缓存 。 这 个 类 能 够 缓存 文件 到 
磁盘 的 指定 目录 。 但 是 为 了 使 用 ImageLoader ， 我 们 应 该 提供 一 个 自 定 义 的 内 存 LRC bitmap 
缓存 ， 这 个 缓存 实现 了 ImageLoader.Imagecache 接口 。 我 们 可 能 想 把 缓存 设置 成 一 个 单 例 。 
关于 更 多 的 有 关内 容 ， 请 参考 建立 请 求 队列 . 


下 面 是 一 个 内 存 LruBitmapCache 类 的 实现 示例 。 它 继承 LruCache 类 并 实现 了 


ImageLoader.ImageCache 接口 : 


import android.graphics.Bitmap; 

import android.support.v4.util.LruCache; 

import android.util.DisplayMetrics; 

import com.android.volley.toolbox.ImageLoader.ImageCache; 


public class LruBitmapCache extends LruCache<String, Bitmap» 
implements ImageCache { 


public LruBitmapCache(int maxSize) { 
super (maxSize); 


public LruBitmapCache(Context ctx) { 
this(getCacheSize(ctx)); 


@Override 
protected int sizeOf(String key, Bitmap value) { 
return value.getRowBytes() * value.getHeight(); 


@Override 
public Bitmap getBitmap(String url) { 
return get(url); 


@Override 
public void putBitmap(String url, Bitmap bitmap) { 
put(url, bitmap); 


// Returns a cache size equal to approximately three screens worth of images. 
public static int getCacheSize(Context ctx) { 

final DisplayMetrics displayMetrics = ctx.getResources(). 

getDisplayMetrics(); 

final int screenWidth = displayMetrics.widthPixels; 

final int screenHeight = displayMetrics.heightPixels; 

// 4 bytes per pixel 

final int screenBytes = screenWidth * screenHeight * 4; 


return screenBytes * 3; 


下 面 是 如 何 实例 化 一 个 ImageLoader 来 使 用 这 个 cache: 


RequestQueue mRequestQueue; // assume this exists. 
ImageLoader mImageLoader = new ImageLoader(mRequestQueue, new LruBitmapCache(LruBitmap 
Cache.getCacheSize())); 


请 求 JSON 


Volley 提供 了 以 下 的 类 用 来 执行 JSON 请 求 : 


* JsonArrayRequest 一 一 一 个 为 了 获取 给 定 URL 的 JSONArray 响应 正文 的 请 求 。 
* JsonobjectRequest 一 一 一 个 为 了 获取 给 定 URL 的 JSONObject 响应 正文 的 请 求 。 允 许 
传 进 一 个 可 选 的 JSONObject 作为 请 求 正 文 的 一 部 分 


这 两 个 类 都 是 基于 一 个 公共 基 类 JsonRequest 。 我 们 遵循 我 们 在 其 它 请 求 类 型 使 用 的 同样 的 
基本 模式 来 使 用 这 些 类 。 如 下 演示 了 如 果 获 取 一 个 JSON feed 并 显示 到 Ul 上 : 


TextView mTxtDisplay; 

ImageView mImageView; 

mTxtDisplay - (TextView) findViewById(R.id.txtDisplay); 
String url - "http://my-json-feed"; 


JsonObjectRequest jsObjRequest - new JsonObjectRequest 
(Request.Method.GET, url, null, new Response.Listener() ( 


QOverride 
public void onResponse(JSONObject response) { 
mTxtDisplay.setText("Response: " + response.toString()); 


} 


}, new Response.ErrorListener() { 
@Override 


public void onErrorResponse(VolleyError error) { 
// TODO Auto-generated method stub 


3); 
// Access the RequestQueue through your singleton class. 


MySingleton.getInstance(this).addToRequestQueue( jsObjRequest); 


关于 基于 Gson 实现 一 个 自 定 义 的 ISON 请 求 对 象 ， 请 参考 下 一 节 课 : 实现 一 个 自 定义 的 请 


实现 自 定 义 的 网 络 请 求 


编写 :kesenhoo - 原文 :http://developer.android.com/training/volley/request-custom.html 


这 节 课 会 介绍 如 何 实现 自 定义 的 请 求 类 型 ， 这 些 自 定义 的 类 型 不 属于 Volley 内 置 支持 包 里 
de 


x 


编写 一 个 自 定 义 请 求 


大 多 数 的 请 求 类 型 都 已 经 包含 在 Volley 的 工具 箱 里 面 。 如 果 我 们 的 请 求 返 回 数值 是 一 个 
string > image 或 者 JSON， 那 么 是 不 需要 自己 去 实现 请 求 类 的 。 


对 于 那些 需要 自 定义 的 请 求 类 型 ， 我 们 需要 执行 以 下 操作 : 


e 继承 Request<T> 类 ， <T> 表示 解析 过 的 响应 请 求 预 期 的 数据 类 型 。 因 此 如 果 我 们 需要 
解析 的 响应 类 型 是 一 个 String， 可 以 通过 继承 Request<String> 来 创建 自 定义 的 请 求 。 
请 参考 Volley 工具 类 中 的 StringRequest 与 ImageRequest 来 学 习 如 何 继承 
Request<T> ° 


e 实现 抽象 方法 parseNetworkResponse() 与 deliverResponse() > 下面 会 详细 介绍 。 


parseNetworkResponse 


=a Response 封装 了 用 于 发 送 的 给 定 类 型 (例如 ， string ^ image ^ JSON 等 ) 解析 过 的 响 
应 。 下 面 会 演示 如 何 实现 parseNetworkResponse() 


@Override 
protected Response<T> parseNetworkResponse( 
NetworkResponse response) { 
try { 
String json = new String(response.data, 
HttpHeaderParser .parseCharset(response.headers) ); 
return Response.success(gson.fromJson(json, clazz), 
HttpHeaderParser .parseCacheHeaders(response) ); 


} 


// handle errors 


* parseNetworkResponse() 的 参数 是 类 型 是 NetworkResponse ， 这 种 参数 以 byte[]、 HTTP 
status code 以 及 response headers 的 形式 包含 响应 负载 。 


e 我 们 实现 的 方法 必须 返回 一 个 Response<T> ， 它 包含 了 我 们 指定 类 型 的 响应 对 象 与 缓存 
metadata 或 者 是 一 个 错误 。 


如 果 我 们 的 协议 没有 标准 的 缓存 机 制 ， 那 么 我 们 可 以 自己 建立 一 个 cache.Entry ,但 是 大 多 数 
请 求 都 可 以 用 下 面 的 方式 来 处 理 : 


return Response.success(myDecodedObject, 
HttpHeaderParser.parseCacheHeaders(response)); 


Volley 在 工作 线程 中 执行 parseNetworkResponse() 方法 。 这 确保 了 耗 时 的 解析 操作 ， 例 如 
decode 一 张 JPEG 图 片 成 bitmap， 不 会 阻塞 UI 线程 。 
deliverResponse 


Volley 会 把 parseNetworkResponse() 方法 返回 的 数据 带 到 主线 程 的 回调 中 。 如 下 所 示 : 


protected void deliverResponse(T response) { 
listener.onResponse(response); 


Example: GsonRequest 


Gson 是 一 个 使 用 映射 支持 JSON 4 Java 对 象 之 间 相 互 转换 的 库 文 件 。 我 们 可 以 定义 与 
JSON keys 相对 应 名 称 的 Java 对 象 。 把 对 象 传递 给 Gson， 然 后 Gson 会 帮 我 们 为 对 象 卉 充 
字段 值 。 下 面 是 一 个 完整 的 示例 : 演示 了 使 用 Gson 解析 Volley 数据 : 


public class GsonRequest<T> extends Request<T> { 
private final Gson gson - new Gson(); 
private final Class<T> clazz; 
private final Map<String, String» headers; 
private final Listener<T> listener; 


Jee 
* Make a GET request and return a parsed object from JSON. 
* 
* @param url URL of the request to make 
* Qparam clazz Relevant class object, for Gson's reflection 
* @param headers Map of request headers 
s 
public GsonRequest(String url, Class<T> clazz, Map<String, String» headers, 
Lastenersi> listener, Errorlastener errorbuxstener) { 
super(Method.GET, url, errorListener); 
this.clazz = clazz; 
this.headers = headers; 
this.listener = listener; 


} 

@Override 

public Map<String, String> getHeaders() throws AuthFailureError { 
return headers != null ? headers : super.getHeaders(); 

} 

@Override 


protected void deliverResponse(T response) { 
listener .onResponse(response); 


@Override 
protected Response<T> parseNetworkResponse(NetworkResponse response) { 
vant 
String json = new String( 
response.data, 
HttpHeaderParser .parseCharset(response.headers) ); 
return Response. success( 
gson.fromJson(json, clazz), 
HttpHeaderParser .parseCacheHeaders(response) ); 
} catch (UnsupportedEncodingException e) { 
return Response.error(new ParseError(e)); 
} catch (JsonSyntaxException e) { 
return Response.error(new ParseError(e)); 


如 果 你 愿意 使 用 的 话 ，Volley 提供 了 现成 的 JsonArrayRequest “J JsonArrayObject X ° 47 
上 一 课 创建 标准 的 网 络 请 求 。 


实现 自 定 义 的 网 络 请 求 
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Android 联 系 人 信息 与 位 置信 息 


编写 :spencer198711,Muyangmin - 原文 :http://developer.android.com/training/building- 
userinfo.html 


这 几 节 课 为 大 家 介绍 如 何在 我 们 的 app 中 添加 用 户 个 人 信息 。 我 们 可 以 通过 识别 用 户 ， 提 供用 
户 相关 信息 和 提供 用 户 周围 的 位 置信 息 等 方法 来 添加 个 人 信息 。 


Lessons 


访问 联系 人 数据 - Accessing Contacts Data 


如 何 使 用 Android 的 Contacts Provider 来 显示 和 修改 联系 人 信息 。 


位 置信 息 - Making Your App Location-Aware 


如 何 通过 获得 用 户 当 前 位 置 来 给 我 们 的 App 添 加 定位 功能 (位 置 感知 ) 。 


^h 5 :spencer198711 - 原文 :http://developer.android.com/training/contacts- 
provider/index.html 


Contacts Provider 是 用 户 联系 人 信息 的 集中 仓库 ， 它 包含 了 来 自 联系 人 应 用 与 社交 应 用 的 联 
系 人 数据 。 在 我 们 的 应 用 中 ， 我 们 可 以 通过 调用 ContentResolver 方 法 或 者 通过 发 送 Intent 给 
联系 人 应 用 来 访问 Contacts Provider 的 信息 。 


这 个 章节 会 讲解 获取 联系 人 列表 ， 显 示 指 定 联系 人 详情 以 及 通过 intent 来 修改 联系 人 信息 。 
里 介绍 的 基础 技能 能 够 扩展 到 执行 更 复杂 的 任务 。 另 外 ， 这 个 章节 也 会 帮助 我 们 了 解 
Contacts Provider 的 整个 架构 与 操作 方法 。 


Lessons 


获取 联系 人 列表 
学 习 如 何 获取 联系 人 列表 。 你 可 以 使 用 下 面 的 技术 来 筛选 需 要 的 信息 : 


e 通过 联系 人 名 字 进 行 得 
。 ae j 


e 通过 类 似 电 话 号 码 等 指 


通 选 
选 
^E a 
获取 联系 人 详情 


学 习 如 何 获取 单个 联 o 青 。 一 个 联系 人 的 详细 信息 包括 电话 号 码 与 邮件 地 址 等 等 。 你 
可 以 获取 所 有 的 详细 信息 ， 也 有 可 以 只 获取 指定 类 型 的 详细 数据 ， 例 如 邮件 地 址 。 


使 用 Intents 修 改 联 系 人 信息 
学 习 如 何 通过 发 送 intent 给 联系 人 应 用 来 修改 联系 人 信息 。 
显示 联系 人 头像 


学 习 如 何 显示 QuickContactBadge 小 组 件 。 当 用 户 点 击 联系 人 臂章 (头像 ) 组 件 时 ， 会 打开 一 
个 对 话 框 ， 这 个 对 话 框 会 显示 联系 人 详情 ， 并 提供 操作 按钮 来 处 理 详 细 信 息 。 例 如 ， 如 果 联 
系 人 信息 有 邮件 地 址 ， 这 个 对 话 框 可 以 显示 一 个 启动 默认 邮件 应 用 的 操作 按钮 。 


获取 联系 人 列表 


编写 :spencer198711 - 原文 :http://developer.android.com/training/contacts- 
provider/retrieve-names.html 


这 一 课 展 示 了 如 何 根据 要 搜索 的 字符 串 去 匹配 联系 人 的 数据 ， 从 而 得 到 联系 人 列表 ， 你 可 以 
使 用 以 下 方法 去 实现 : 


匹配 联系 人 名 字 


通过 搜索 字符 串 来 匹配 联系 人 名 字 的 全 部 或 者 部 分 来 获得 联系 人 列表 。 因 为 Contacts 
Provider 允 许多 个 实例 拥有 相同 的 名 字 ， 所 以 这 种 方法 能 够 返回 匹配 的 列表 。 


匹配 特定 的 数据 类 型 ， 比 如 电话 号 码 


通过 搜索 字符 串 来 匹配 联系 人 的 某 一 特定 数据 类 型 (如 电子 邮件 地 址 ) ， 来 取得 符合 要 求 的 
联系 人 列表 。 例 如 ， 这 种 方法 可 以 列 出 电子 邮件 地 址 与 搜索 字符 相 匹 配 的 所 有 联系 人 。 


匹配 任意 类 型 的 数据 


通过 搜索 字符 串 来 匹配 联系 人 详情 的 所 有 数据 类 型 ， 包 括 名 字 、 电 话 号 码 、 地 址 、 电 子 邮 件 
地 址 等 等 。 例 如 ， 这 种 方法 接受 任意 数据 类 型 的 搜索 字符 串 ， 并 列 出 与 这 个 搜索 字符 串 相 匹 
配 的 联系 人 。 


Note : 这 一 课 的 所 有 例子 都 使 用 CursorLoader 获 取 Contacts Provider 中 的 数据 。 
CursorLoader 在 一 个 与 Ul 线程 相 独 立 的 工作 线程 进行 查询 操作 。 这 保证 了 数据 查询 不 会 
降低 Ul 响应 的 时 间 ， 以 免 引 起 模 糕 的 用 户 体 验 。 更 多 信息 ， 请 参照 在 后 台 加 载 数据 。 


请 求 读 取 联 系 人 的 权限 


为 了 能 够 在 Contacts Provider 中 做 任意 类 型 的 搜索 ， 我 们 的 应 用 必须 拥有 READ_CONTACTS 
权限 。 为 了 拥有 这 个 权限 ， 我 们 需要 在 项 目的 manifest 文 件 的 节点 中 添加 子 结 点 ， 如 下 : 


«uses-permission android:name-"android.permission.READ CONTACTS" /> 


根据 名 字 取 得 联系 人 并 列 出 结果 


这 种 方法 根据 搜索 字符 串 ， 去 匹配 Contacts Provider 的 ContactsContract.Contacts 表 中 的 联系 
人 名 字 。 通 常 希 望 在 ListView 中 展示 结果 ， 去 让 用 户 在 所 有 匹配 的 联系 人 中 做 选择 。 


定义 ListView 和 列表 项 的 布局 


为 了 能 够 将 搜索 结果 展示 在 列表 中 ， 我 们 需要 一 个 包含 ListView 以 及 其 他 布局 控件 的 主 布局 文 
件 ， 和 一 个 定义 列表 中 每 一 项 的 布局 文件 。 例 如 ， 可 以 使 用 以 下 XML 代 码 去 创建 主 布局 文件 
res/layout/contacts list view.xml : 


<?xml version="1.0" encoding="utf-8"?> 

«ListView xmlns:android-"http://schemas.android.com/apk/res/android" 
android:id="@android:id/list" 
android: layout_width="match_parent" 
android: layout_height="match_parent"/> 


这 个 XML 代码 使 用 了 Android 内 建 的 ListView 控 件 , 他 的 id 是 android:idy/list ° 


使 用 以 下 XML 代码 定义 列表 项 布局 文件 contacts_list_item.xml : 


<?xml version="1.0" encoding="utf-8"?> 

«TextView xmlns:android-"http://schemas.android.com/apk/res/android" 
android:id="@android:id/texti" 
android: layout_width="match_parent" 
android: layout_height="wrap_content" 
android:clickable="true"/> 


这 个 XML 代码 使 用 了 Android 内 建 的 TextView 控 件 , 他 的 id 是 android:text1 ° 


Note : 本 课 并 不 会 描述 如 何 从 用 户 那里 获取 搜索 字符 串 的 界面 ， 因 为 我 们 可 能 会 间接 地 
获取 这 个 字符 串 。 比 如 说 ， 我 们 可 能 会 给 用 户 一 个 选项 去 输入 文字 信息 ， 把 这 些 文字 信 
息 作为 搜索 字符 串 去 匹配 联系 人 的 名 字 。 


刚刚 写 的 这 两 个 布局 文件 定义 了 一 个 显示 ListView 的 用 户 界面 。 下 一 步 是 编写 使 用 这 个 用 户 界 
面 显 示 联 系 人 列表 的 代码 。 


定义 一 个 显示 联系 人 列表 的 Fragment 


为 了 显示 联系 人 列表 ， 需 要 定义 一 个 由 Activity 加 载 的 Fragment。 使 用 Fragment 是 一 个 比较 灵 
活 的 方法 ， 因 为 我 们 可 以 使 用 一 个 Fragment 去 显示 列表 ， 用 另 一 个 Fragment 显 示 用 户 在 列表 
中 选择 的 联系 人 的 详情 。 使 用 这 种 方式 ， 我 们 可 以 将 本 课程 中 展示 的 方法 和 另外 一 课 获 取 联 
系 人 详情 的 方法 联系 起 来 。 

想 要 学 习 如 何在 Activity 中 使 用 一 个 或 者 多 个 Fragment， 请 阅读 培训 课程 使 用 Fragment 建 立 动 


ŠUI ° 


为 了 方便 我 们 编写 对 Contacts Provider 的 查询 ，Android 框 架 提供 了 一 个 叫做 
ContactsContract 的 契约 类 ， 这 个 类 定义 了 一 些 对 查询 Contacts Provider 很 有 用 的 常量 和 方 
法 。 当 我 们 使 用 这 个 类 的 时 候 ， 我 们 不 用 自己 定义 内 容 URI、 表 名 、 列 名 等 常量 。 使 用 这 个 


类 ， 只 需要 引入 以 下 类 声明 : 


import android.provider.ContactsContract; 


由 于 代码 中 使 用 了 CursorLoader 去 获取 provider 的 数据 ， 所 以 我 们 必须 实现 加 载 器 接口 
LoaderManager.LoaderCallbacks。 同 时 ， 为 了 检测 用 户 从 结果 列表 中 选择 了 哪 一 个 联系 人 ， 
必须 实现 适配器 接口 AdapterView.OnltemClickListener。 例 如 : 


import android.support.v4.app.Fragment; 
import android.support.v4.app.LoaderManager.LoaderCallbacks; 
import android.widget.AdapterView; 


public class ContactsFragment extends Fragment implements 
LoaderManager.LoaderCallbacks«Cursor», 
AdapterView.OnItemClickListener { 


定义 在 其 他 代 部 分 码 中 使 用 的 全 局 变量 : 


* Defines an array that contains column names to move from 
* the Cursor to the ListView. 
A 
QSuppressLint("InlinedApi") 
private final static String[] FROM COLUMNS = { 
Build.VERSION.SDK INT 
»- Build.VERSION CODES.HONEYCOMB ? 
Contacts.DISPLAY NAME PRIMARY : 
Contacts.DISPLAY NAME 
u 
/* 
* Defines an array that contains resource ids for the layout views 
* that get the Cursor column contents. The id is pre-defined in 
* the Android framework, so it is prefaced with "android.R.id" 
i 
private final static int[] TO IDS = { 
android.R.id.text1 
}; 
// Define global mutable variables 
// Define a ListView object 
ListView mContactsList; 
// Define variables for the contact the user selects 
// The contact's ID value 
long mContactId; 
// The contact's LOOKUP KEY 
String mContactKey; 
// A content URI for the selected contact 
Uri mContactUri; 
// An adapter that binds the result Cursor to the ListView 
private SimpleCursorAdapter mCursorAdapter; 


Note : 4 f Contacts.DISPLAY NAME PRIMARY $ € Android 3.0 《API 版 本 11) 或 
者 更 高 的 版 本 才能 使 有 用， 如果 应 用 的 minSdkVersion 是 10 或 者 更 低 ， 会 在 eclipse 中 产生 
警告 信息 。 为 了 关闭 这 个 警告， 我 们 可 以 在 FROM_COLUMNS 定 义 之 前 加 上 
@SuppressLint("InlinedApi") 注 解 。 


初始 化 Fragment 


为 了 初始 化 Fragment ，Android 系 统 需要 我 们 为 这 个 Fragment 添 加 空 的 、 公 有 的 构造 方法 ， 
同时 在 回调 方法 onCreateView() 中 绑 定 界面 。 例 如 : 
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// Empty public constructor, required by the system 
public ContactsFragment() {} 
// A UI Fragment must inflate its View 
@Override 
public View onCreateView(LayoutInflater inflater, ViewGroup container, 
Bundle savedInstanceState) { 
// Inflate the fragment layout 
return inflater.inflate(R.layout.contact_list_fragment, 
container, false); 


A ListView? £ CursorAdapter 


设置 SimpleCursorAdapter， 将 搜索 结果 绑 定 到 ListView。 为 了 获得 显示 联系 人 列表 的 
ListView 控 件 ， 需 要 使 用 Fragment 的 父 Activity 调 用 Activity.findViewByld()。 当 调用 
setAdapter() 的 时 候 ， 需 要 使 用 父 Activity 的 上 下 文 (Context) 。 


public void onActivityCreated(Bundle savedInstanceState) { 
super.onActivityCreated(savedInstanceState); 


// Gets the ListView from the View list of the parent activity 
mContactsList - 
(ListView) getActivity().findViewById(R.layout.contact list view); 

// Gets a CursorAdapter 
mCursorAdapter - new SimpleCursorAdapter( 

getActivity(), 

R.layout.contact list item, 

null, 

FROM COLUMNS, TO IDS, 

9); 
// Sets the adapter for the ListView 
mContactsList.setAdapter(mCursorAdapter); 


为 选择 的 联系 人 设置 监听 器 


当 我 们 显示 搜索 列表 结果 的 时 候 ， 我 们 通常 会 让 用 户 选择 某 一 个 联系 人 去 做 进一步 的 处 理 。 
例如 ， 当 用 户 选 择 某 一 个 联系 人 的 时 候 ， 可 以 在 地 图 eds 。 为 了 能 够 提 
供 这 个 功能 ， 我 们 需要 定义 当前 的 Fragment 为 一 个 点 击 监听 器 ， 这 需要 这 个 类 实现 
AdapterView.OnltemClickListener 接 口 ， 就 像 前 面 介 绍 的 定义 显示 联系 人 列表 的 Fragment 那 


这 个 监听 器 ， 需 要 在 onActivityCreated() 方 法 中 调用 setOnltemClickListener() 以 使 得 
E AE E ListView ° 例如: 


public void onActivityCreated(Bundle savedInstanceState) { 


// Set the item click listener to be the current fragment. 
mContactsList.setOnItemClickListener(this); 


由 于 指定 了 当前 的 Fragment 作 为 ListView 的 点 击 监听 器 ， 现 在 我 们 需要 实现 处 理 点 击 事件 的 
onltemClick() 方 法 。 这 个 会 在 随后 讨论 。 


定义 查询 映射 


定义 一 个 常量 ， 这 个 常量 包含 我 们 想 要 从 查询 结果 中 返回 的 列 。Listview 中 的 每 一 项 
个 联系 人 的 名 字 。 在 Android 3.0 (API version 11) 或 者 更 高 的 版 本 ， 这 个 列 的 名 字 
Contacts.DISPLAY NAME. PRIMARY ; 在 Android 3.0 之 前 ， 这 个 列 的 名 字 是 
Contacts.DISPLAY_NAME 。 


示 了 一 


日 
NA 

日 
Fe 


在 SimpleCursorAdapter 绑 定 过 程 中 会 用 到 Contacts. ID 列 。 Contacts. ID 和 LOOKUP KEY 
一 同 用 来 构建 用 户 选择 的 联系 人 的 内 容 URI。 


QSuppressLint("InlinedApi") 
private static final String[] PROJECTION = { 
Contacts. ID, 
Contacts.LOOKUP KEY, 
Build.VERSION.SDK INT 
»- Build.VERSION CODES.HONEYCOMB ? 
Contacts.DISPLAY NAME PRIMARY : 
Contacts.DISPLAY NAME 


z 3 Cursorf2 7| € 5| # = 


为 了 从 Cursor 中 获得 单独 某 一 列 的 数据 ， 我 们 需要 知道 这 一 列 在 Cursor 中 的 索引 值 。 我 们 需 
要 定义 Cursor 列 的 索引 值 ， 这些 索引 值 与 我 们 定义 查询 映射 的 列 的 顺序 是 一 样 的 。 例 如 : 


// The column index for the _ID column 

private static final int CONTACT ID INDEX = 0; 
// The column index for the LOOKUP KEY column 
private static final int LOOKUP KEY INDEX - 1; 


为 了 指定 我 们 想 要 的 数据 ， 我 们 需要 创建 一 个 包含 文本 表达 式 和 变量 的 组 合 ， 去 告诉 provider 
我 们 需要 的 数据 列 和 想 要 的 值 。 


对 于 文本 表达 式 ， 定 义 一 个 常量 ， 列 出 所 有 搜索 到 的 列 。 尽 管 这 个 表达 式 可 以 包含 变量 值 ， 
但 是 建议 用 "2" 占 位 符 来 替代 这 个 值 。 在 搜索 的 时 候 ， E EE A E 
使 用 "?" 占 位 符 确保 了 搜索 条 件 是 由 绑 定 产生 而 不 是 由 SQL 编译 产生 。 这 个 方法 消除 了 恶意 
SQL 注入 的 可 能 。 例 如 : 


// Defines the text expression 

@SuppressLint("InlinedApi") 

private static final String SELECTION = 
Build. VERSION.SDK_INT >= Build.VERSION CODES.HONEYCOMB ? 
Contacts.DISPLAY_NAME_PRIMARY + " LIKE ?" 
Contacts.DISPLAY NAME + " LIKE ?"; 

// Defines a variable for the search string 

private String mSearchString; 

// Defines the array to hold values that replace the ? 

private String[] mSelectionArgs - ( mSearchString j; 


定义 onltemClick() 方 法 


在 之 前 的 内 容 中 ， 我 们 为 Listview 设 置 了 列表 项 点 击 监听 器 ， 现 在 需要 定义 
AdapterView.OnltemClickListener.onltemClick() 方 法 以 实现 监听 器 行为 : 


@Override 
public void onItemClick( 
AdapterView<?> parent, View item, int position, long rowID) { 
// Get thexCursor 
Cursor cursor = parent.getAdapter().getCursor(); 
// Move to the selected contact 
cursor .moveToPosition(position) ; 
// Get, the STD value 
mContactId = getLong(CONTACT ID INDEX); 
// Get the selected LOOKUP KEY 
mContactKey = getString(CONTACT KEY INDEX); 
// Create the contact's content Uri 
mContactUri = Contacts.getLookupUri(mContactId, mContactKey); 
/* 
* You can use mContactUri as the content URI for retrieving 
* the details for a contact. 
a7, 


始 化 Loader 


由 于 使 用 了 CursorLoader 获 取 数 据 ， 我 们 必须 初始 化 后 台 线 程 和 其 他 的 控制 异步 获取 数据 的 
变量 。 需 要 在 onActivityCreated() 方 法 中 做 初始 化 的 工作 ， 这 个 方法 是 在 Fragment 的 界面 显示 
之 前 被 调用 的 ， 相 关 代 码 展 示 如 下 : 


public class ContactsFragment extends Fragment implements 
LoaderManager .LoaderCallbacks<Cursor> { 


// Called just before the Fragment displays its UI 

@Override 

public void onActivityCreated(Bundle savedInstanceState) { 
// Always call the super method first 
super.onActivityCreated(savedInstanceState) ; 


// Initializes the loader 
getLoaderManager().initLoader(0, null, this); 


3: 3Ói LonCreateLoader() 7 7X 


我 们 需要 实现 onCreateLoader() 方 法 ， 这 个 方法 是 在 调用 initLoader() 后 马上 被 loader 框 架 调用 
的 。 


在 onCreateLoader() 方 法 中 ， 设 置 搜 索 字 符 串 模式 。 为 了 让 一 个 字符 串 符合 一 个 模式 ， 插 
入 "%" 字 符 代 表 0 个 或 多 个 字符 ， 插 入 " "代表 一 个 字符 。 例 如 ， 模 式 %Jefferson% 将 会 匹 
&t“Thomas Jefferson” 和 “Jefferson Davis" ° 


这 个 方法 返回 一 个 CursorLoader 对 象 。 对 于 内 容 URI， 则 使 用 了 Contacts.CONTENT_URI; 
这 个 URI 关 联 到 整个 表 ， 例 子 如 下 所 示 : 


@Override 
public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) { 
/* 
* Makes search string into pattern and 
* stores it in the selection array 
xA 
mSelectionArgs[0] = "%" + mSearchString + "%"; 
// Starts the query 
return new CursorLoader( 
getActivity(), 
Contacts.CONTENT URI, 
PROJECTION, 
SELECTION, 
mSelectionArgs, 
null 


); 


实现 onLoadFinished() 方 法 和 onLoaderReset() 方 法 


实现 onLoadFinished() 方 法 。 当 Contacts Provider 和 返回 查 询 结果 的 时 候 ，loader 框 架 会 调用 
onLoadFinished() 方 法 。 在 这 个 方法 中 ， 将 查询 结果 Cursor 传 给 SimpleCursorAdapter， 这 将 
会 使 用 这 个 搜索 结果 自动 更 新 ListView 。 


public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) { 
// Put the result Cursor in the adapter for the ListView 


mCursorAdapter.swapCursor(cursor); 


当 loader 框 架 检测 到 结果 集 Cursor 包 含 过 时 的 数据 时 ， 它 会 调用 onLoaderReset()。 我 们 需要 
删除 SimpleCursorAdapter 对 已 经 存在 Cursor 的 引用 。 如 果 不 这 么 做 的 话 ，loader 框 架 将 不 会 
回收 Cursor 对 象 ， 这 将 会 导致 内 存 泄漏 。 例 如 : 


@Override 
public void onLoaderReset(Loader<Cursor> loader) { 
// Delete the reference to the existing Cursor 


mCursorAdapter.swapCursor(null); 


我 们 现在 已 经 实现 了 一 个 应 用 的 关键 部 分 ， 即 根据 搜索 字符 串 匹 配 联系 人 名 字 和 将 获得 的 结 
果 展 示 在 ListView 中 。 用 户 可 以 点 击 选择 一 个 联系 人 名 字 ， 这 将 会 触发 一 个 监听 器 ， 在 监听 器 
的 回调 函数 中 ， 你 可 以 使 用 此 联系 人 的 数据 做 进一步 的 处 理 。 例 如 ， 你 可 以 进一步 获取 此 联 
系 人 的 详情 ， 想 要 知道 何如 获取 联系 人 详情 ， 请 继续 学 习 下 一 课 获 取 联 系 人 详情 。 


想 要 了 解 更 多 搜索 用 户 界面 的 知识 ， 请 参考 API 指 南 Creating a Search Interface 。 


这 一 课 的 以 下 内 容 展 示 了 在 Contacts Provider 中 查找 联系 人 的 其 他 方法 。 


根据 特定 的 数据 类 型 匹配 联系 人 


这 种 方法 可 以 让 我 们 指定 想 要 匹配 的 数据 类 型 。 根 据 名 字 去 检索 是 这 种 类 型 的 查询 的 一 个 具 
体例 子 。 但 也 可 以 用 任何 与 联系 人 详情 数据 相关 的 数据 类 型 去 做 查询 。 例 如 ， 我 们 可 以 检索 
具有 特定 邮政 编码 联系 人 ， 在 这 种 情况 下 ， 搜 索 字 符 串 将 会 去 匹配 存储 在 一 个 邮政 编码 列 中 
的 数据 。 
为 了 实现 这 种 类 型 的 检索 ， 首 先 实 现 以 下 的 代码 ， 正 如 之 前 的 内 容 所 展示 的 : 

e 请 求 读 取 联系 人 的 权限 

e 定义 列表 和 列表 项 的 布局 


e 定义 显示 联系 人 列表 的 Fragment 
e 定义 全 局 变量 


e 初始 化 Fragment 

e 为 ListView 设 置 CursorAdapter 
e 设置 选择 联系 人 的 监听 器 

e 定义 Cursor 的 列 索 引 常量 


尽管 我 们 现在 从 不 同 的 表 中 取 数 据 ， 检 索 列 的 映射 顺序 是 一 样 的 ， 所 以 我 们 可 以 为 这 个 
Cursor 使 用 同样 的 索引 常量 。 


e 定义 onltemClick() 方 法 
e 初始 化 loader 
e 实现 onLoadFinished() 方 法 和 onLoaderReset() 方 法 


为 了 将 搜索 字符 串 匹 配 特定 的 详 请 数据 类 型 并 显示 结果 ， 以 下 的 步骤 展示 了 我 们 需要 额外 添 
加 的 代码 。 


选择 要 查询 的 数据 类 型 和 数据 库 表 


为 了 从 特定 类 型 的 详 请 数据 中 查询 ， 我 们 必须 知道 的 数据 类 型 的 自 定义 MIME 类 型 的 值 。 每 一 
个 数据 类 型 拥有 唯一 的 MIME 类 型 值 ， 这 个 值 在 ContactsContract.CommonDataKinds 的 子 类 
中 被 定义 为 常量 CONTENT_ITEM_TYPE ， 并 且 与 实际 的 数据 类 型 相关 。 子 类 的 名 字 会 表明 它们 的 
实际 数据 类 型 。 例 如 ，email 数 据 的 子 类 是 contactsContract.CcommonDataKinds.Email ， 并 且 


email 的 自 定义 MIME 类 型 是 Email.CONTENT ITEM TYPE ° 


在 搜索 中 需要 使 用 ContactsContract.Data 类 。 同 时 所 有 需要 的 常量 ， 包 括 数据 映射 、 选 择 字 
如、 排序 规则 都 是 由 这 个 类 定义 或 继承 自 此 类 。 


定义 查询 映射 


为 了 定义 一 个 查询 映射 ， 请 选择 一 个 或 者 多 个 定义 在 ContactsContract.Data 表 或 其 子 类 的 
列 。Contacts Provider 在 返回 行 结 果 集 之 前 ， 隐 式 的 连接 了 ContactsContract.Data 表 和 其 他 
表 。 例 如 : 


@SuppressLint("InlinedApi") 
private static final String[] PROJECTION = { 


/* 
* The detail data row ID. To make a ListView work, 
* this column is required. 
uA 

Data. ID, 


// The primary display name 
Build.VERSION.SDK INT »- Build.VERSION CODES.HONEYCOMB ? 
Data.DISPLAY NAME PRIMARY : 
Data.DISPLAY NAME, 
// The contact's ID, to construct a content URI 
Data.CONTACT ID 
// The contact's LOOKUP KEY, to construct a content URI 
Data.LOOKUP KEY (a permanent link to the contact 


定义 查询 标准 
为 了 根据 特定 的 联系 人 数据 类 型 查询 字符 串 ， 请 按照 以 下 方法 构建 查询 选择 子 幼 : 


e 包含 搜索 字符 串 的 列 名 。 这 个 名 字 根 据 数 据 类 型 所 变化 ， 所 以 我 们 需要 找到 与 数据 类 型 
对 应 的 ContactsContract.CommonDataKinds 的 子 类 ， 并 从 这 个 子 类 中 选择 列 名 。 例 如 ， 
想 要 搜索 email 地 址 ， 需 要 使 用 Email.ADDRESS 列 。 

e 搜索 字符 串 本 身 ， 请 在 查询 选择 子 多 里 使 用 "?" 表 示 。 

e 列 名 包含 自 定 义 的 MIME 类 型 值 。 这 个 列 名 字 总 是 Data.MIMETYPE ° 

e 自 定 义 MIME 类 型 值 的 数据 类 型 。 如 之 前 描述 ， 这 需要 使 用 
ContactsContract.CommonDataKinds 子 类 中 的 CONTENT_ITEM_TYPE 常量 。 例 如 ，email 数 
据 的 MIME 类 型 值 是 Email.CONTENT_ITEM_TYPE 。 需 要 在 这 个 常量 值 的 开头 和 结尾 加 
E" ( 单 引号 ) 。 否 则 ，provider 会 把 这 个 值 翻译 成 一 个 变量 而 不 是 一 个 字符 串 。 我 们 不 
需要 为 这 个 值 提供 占 位 符 ， 因 为 我 们 在 使 用 一 个 常量 而 不 是 用 户 提供 的 值 。 例 如 : 


JE 
* Constructs search criteria from the search string 
* and email MIME type 


n 
private static final String SELECTION - 

/* 
* Searches for an email address 
* that matches the search string 
2 

Email.ADDRESS + " LIKE ? " + "AND " + 

/* 
* Searches for a MIME type that matches 
* the value of the constant 
* Email.CONTENT ITEM TYPE. Note the 
* single quotes surrounding Email.CONTENT ITEM TYPE. 
yf 

Data.MIMETYPE + " = '" + Email.CONTENT ITEM TYPE + "'"; 


String mSearchString; 
String[] mSelectionArgs = { "" }; 


实现 onCreateLoader() 方 法 


现在 ， 我 们 已 经 详 述 了 想 要 的 数据 和 如 何 找到 这 些 数据 ， 如 何在 onCreateLoader() 方 法 中 定义 
一 个 查询 。 使 用 你 的 数据 映射 、 查 询 选 择 表达 式 和 一 个 数组 作为 选择 表达 式 的 参数 ， 并 从 这 
个 方法 中 返回 一 个 新 的 CursorLoader 对 象 。 而 内 容 URI 需 要 使 用 Data.CONTENT_URI， 你 

如 : 


@Override 
public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) { 
// OPTIONAL: Makes search string into pattern 
mSearchString = "9" + mSearchString + "%"; 
// Puts the search string into the selection criteria 
mSelectionArgs[9] = mSearchString; 
// Starts the query 
return new CursorLoader( 
getActivity(), 
Data.CONTENT_URI, 
PROJECTION, 
SELECTION, 
mSelectionArgs, 
null 


); 


这 段 代 码 片 段 是 基于 特定 的 联系 人 详情 数据 类 型 的 简单 反 向 查找 。 如 果 我 们 的 应 用 关注 于 某 
一 种 特定 的 数据 类 型 ， 比 如 说 email 地 址 ， 并 且 人 允许 用 户 获 得 与 此 数据 相关 的 联系 人 名 字 ， 这 
种 形式 的 查询 是 最 好 的 方法 。 


根据 任意 类 型 的 数据 匹配 联系 人 


根据 任意 数据 类 型 获取 联系 人 时 ， 如 果 联 系 人 的 数据 (这些 数据 包括 名 字 、email 地 址 、 邮 件 
地 址 和 电话 号 码 等 等 ) 能 匹配 要 搜索 的 字符 串 ， 那 么 该 联系 人 信息 将 会 被 返回 。 这 种 搜索 结 

果 会 比较 广泛 。 例 如 ， 如 果 搜 索 字 符 串 是 "Doe"， 搜 索 任 意 类 型 的 数据 将 会 返回 名 字 为 "Jone 
Doe" 的 联系 人 ， 也 会 返回 一 个 住 在 "Doe Street" 的 联系 人 。 


为 了 完成 这 种 类 型 的 查询 ， 就 像 之 前 展示 的 那样 ， 首 先 需要 实现 以 下 代码 : 


e. 请 求 读 取 联 系 人 的 权限 

e 定义 列表 和 列表 项 的 布局 

e 定义 显示 联系 人 列表 的 Fragment 
e 定义 全 局 变量 

e 初始 化 Fragment 

为 ListView 设 置 CursorAdapter 
设置 选择 联系 人 的 监听 器 

定义 Cursor 的 列 索 引 常量 


对 于 这 种 形式 的 查询 ， 你 需要 使 用 与 在 "使 用 特定 类 型 的 数据 匹配 联系 人 ” 那 一 节 中 相同 的 
表 ， 也 可 以 使 用 相同 的 列 索 引 。 
e 定义 onltemClick() 方 法 
e 初始 化 loader 
e 实现 onLoadFinished() 方 法 和 onLoaderReset() 方 法 
以 下 的 步骤 展示 了 为 了 能 够 根据 任意 的 数据 类 型 去 匹配 查询 字符 串 并 显示 结果 列表 ， 我 们 需 
要 添加 的 额外 代码 。 


去 除 查询 标准 

不 需要 为 mSelectionArgs 定 义 查询 标准 常量 SELECTION。 这 些 内 容 在 这 种 类 型 的 检索 不 会 被 
用 到 。 

实现 onCreateLoader() 方 法 


实现 onCreateLoader() 方 法 ， 返 回 一 个 新 的 CursorLoader 对 象 。 我 们 不 需要 把 搜索 字符 串 转 
化 成 一 个 搜索 模式 ， 因 为 Contacts Provider 会 自动 做 这 件 事 。 使 用 
Contacts.CONTENT FILTER_URI 作 为 基础 查询 URI， 并 使 用 Uri.withAppendedPath() 方 法 将 


搜索 字符 串 添加 到 基础 URI 中 。 使 用 这 个 URI 会 自动 触发 对 任意 数据 类 型 的 搜索 ， 就 像 以 下 例 
子 所 示 : 


@Override 
public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) { 
/* 
* Appends the search string to the base URI. Always 
* encode search strings to ensure they're in proper 
* format. 
i 
Uri contentUri - Uri.withAppendedPath( 
Contacts.CONTENT FILTER URI, 
Uri.encode(mSearchString)); 
// Starts the query 
return new CursorLoader( 
getActivity(), 
contentUri, 
PROJECTION, 
null, 
null, 
null 


); 


这 段 代 码 片 段 ， 是 想 要 在 Contacts Provider 中 建立 广泛 搜索 类 型 应 用 的 基础 部 分 。 这 种 方法 
对 那些 想 要 实现 与 通讯 录 应 用 联系 人 列表 中 相似 搜索 功能 的 应 用 ， 会 很 有 帮助 。 


获取 联系 人 详情 


编写 :Spencer198711 - 原文 :http://developer.android.com/training/contacts- 
provider/retrieve-details.html 


这 一 课 展示 了 如 何 取得 一 个 联系 人 的 详细 信息 ， 比 如 email 地 址 、 电 话 号 码 等 。 当 使 用 者 去 获 
取 联 系 人 信息 的 时 候 ， 这 些 信息 正 是 他 们 所 查找 的 。 我 们 可 以 给 他 们 关于 一 个 联系 人 的 所 有 
信息 ， 或 者 仅仅 显示 一 个 特定 的 数据 类 型 ， 比 如 email 地 址 。 


这 一 课 假设 你 已 经 获取 到 了 一 个 用 户 所 选取 的 联系 人 的 ContactsContract.Contacts 数 据 项 。 
在 获取 联系 人 名 字 那 一 课 展 示 了 如 何 获取 联系 人 列表 。 


获取 联系 人 的 所 有 详细 信息 


为 了 取得 一 个 联系 人 的 所 有 详情 ， 查找 ContactsContract.Data 表 中 包含 联系 人 LOOKUP_KEY 
列 的 任意 行 。 因 为 Contacts Provider 隐 式 地 连接 了 ContactsContract.Contacts 表 和 
ContactsContract.Data 表 ， 所 以 这 个 LOOKUP_KEY 列 在 ContactsContract.Data 表 中 是 可 用 

的 。 关 于 LOOKUP_KEY 列 ， 在 获取 联系 人 名 字 那 一 课 有 详细 的 描述 。 


Note : 检索 一 个 联系 人 的 所 有 信息 会 降低 设备 的 性 能 ， 因 为 这 需要 检索 
ContactsContract.Data 表 的 所 有 列 。 在 使 用 这 种 方法 之 前 ， 请 认 丨 考虑 对 性 能 影响 。 
请 求 权 限 
为 了 能 够 读 Contacts Provider， 我 们 的 应 用 必须 拥有 READ CONTACTS 权 限 。 为 了 请 求 这 个 


权限 ， 需 要 在 manifest 文 件 的 中 添加 如 下 子 节点 : 


«uses-permission android:name-"android.permission.READ CONTACTS" /> 


设置 查询 映射 


根据 一 行 数 据 的 数据 类 型 ， 它 可 能 会 使 用 很 多 列 或 者 只 使 用 几 列 。 另 外 ， 数 据 会 根据 不 同 的 
数据 类 型 而 出 现在 不 同 的 列 中 。 为 了 确保 能 够 获取 所 有 数据 类 型 的 所 有 可 能 的 数据 列 ， 需 要 
在 查询 映射 中 添加 所 有 列 的 名 字 。 如 果 要 把 Cursor 绑 定 到 ListView， 记 得 要 获取 Data. ID > & 
则 的 话 ， 有 界面 绑 定 就 不 会 起 作用 。 同 时 也 需要 获取 Data.MIMETYPE 列 ， 这 样 才能 识别 我 们 获 
取 到 的 每 一 行 数据 的 数据 类 型 。 例 如 : 


private Static final String PROJECTION = 

Data. ID, 
Data.MIMETYPE, 
Data.DATA1, 
Data.DATA2, 
Data.DATA3, 
Data.DATA4, 
Data.DATAS, 
Data.DATA6, 
Data.DATAT7, 
Data.DATAS8, 
Data.DATA9, 
Data.DATA10, 
Data.DATA11, 
Data.DATA12, 
Data.DATA13, 
Data.DATA14, 
Data.DATA15 


}; 


这 个 查询 映射 使 用 了 ContactsContract.Data 类 中 定义 的 列 名 字 ， 去 获取 
ContactsContract.Data 表 中 一 行 的 所 有 数据 列 。 


我 们 也 可 以 使 用 由 ContactsContract.Data 或 其 子 类 定义 的 列 常量 去 设置 查询 映射 。 需 要 注意 
的 是 ， 从 SYNC1 到 SYNC4 的 数据 列 是 sync adapter 同 步 数 据 所 使 用 的 ， 它 们 的 值 对 我 们 没有 


定义 查询 标准 


为 查询 选择 子 句 定义 一 个 常量 ， 一 个 包含 查询 选择 参数 的 数组 ， 以 及 一 个 保存 查询 选择 值 的 
变量 。 使 用 Contacts.LOOKUP _KEY 列 去 查找 这 个 联系 人 。 例 如 : 


// Defines the selection clause 

private static final String SELECTION = Data.LOOKUP KEY + " = ?"; 
// Defines the array to hold the search criteria 

private String[] mSelectionArgs = { "" }; 

/* 


* 


Defines a variable to contain the selection value. Once you 


* 


have the Cursor from the Contacts table, and you've selected 
* the desired row, move the row's LOOKUP KEY value into this 
* variable. 

E 


private String mLookupKey; 


在 查询 选择 表达 式 中 使 用 eel ， 确 保 了 搜索 是 由 绑 定 生成 而 不 是 由 SQL 编译 生成 。 这 种 
方法 消除 了 恶意 SQL 注入 的 可 能 性 。 


定义 排序 顺序 


定义 在 查询 结果 Cursor 中 希望 的 排序 顺序 。 按 照 Data.MIMETYPE 去 排序 ， 可 以 让 特定 数据 类 
型 的 所 有 行 排列 在 一 起 。 这 种 形式 的 查询 排序 参数 让 所 有 具有 email 的 行 排 在 一 起 ， 让 所 有 具 
有 电话 的 行 排 在 一 起 ...... 例如 : 


TE 

* Defines a string that specifies a sort order of MIME type 
ff 

private static final String SORT_ORDER = Data.MIMETYPE; 


Note : 一 些 数据 类 型 不 使 用 子 类 型 ， 所 以 不 能 按照 子 类 型 来 排序 。 作 为 替代 方法 ， 我 们 
不 得 不 遍历 返回 的 Cursor， 去 判定 当前 行 的 数据 类 型 ， 为 那些 使 用 子 类 型 的 数据 行 保 存 
数据 。 当 读 取 完 cursor 后 ， 我 们 可 以 根据 子 类 型 去 排序 每 一 个 数据 类 型 并 : 


初始 化 查询 loader 


永远 在 后 台 线 程 中 去 检索 Contacts Provider( 或 者 其 他 content provider) 的 数据 。 使 用 Loader 框 
架 中 的 LoaderManager 类 和 LoaderManagerLoaderCallbacks 在 后 台 去 做 获取 数据 的 工作 。 


当 我 们 已 经 准备 好 去 获取 数据 行 ， 需 要 通过 AR 。 传 递 一 
个 Integer 类 型 的 标识 符 给 initLoader() 方 法 ， 这 个 标识 符 会 传递 给 
LoaderManagerLoaderCallbacks 方 法 。 当 在 一 个 应 用 中 使 用 多 个 loader 时 ， 这 个 标识 符 能 够 
帮助 我 们 区 分 它们 。 


以 下 的 代码 片段 展示 了 如 何 初 始 化 loader 框 架 : 


public class DetailsFragment extends Fragment implements 
LoaderManager .LoaderCallbacks<Cursor> { 


// Defines a constant that identifies the loader 
DETAILS QUERY ID = 0; 


Jeu 
* Invoked when the parent Activity is instantiated 
* and the Fragment's UI is ready. Put final initialization 
* steps here. 
i 
@Override 
onActivityCreated(Bundle savedInstanceState) { 


// Initializes the loader framework 
getLoaderManager().initLoader(DETAILS QUERY ID, null, this); 


3: 3Ói LonCreateLoader() 7 7X 


实现 onCreateLoader() 方 法 。loader 框 架 会 在 我 们 调用 initLoader() 方 法 后 立即 调用 
onCreateLoader() 方 法 。 这 个 方法 会 返回 一 个 CursorLoader 对 象 。 由 于 搜索 的 是 
ContactsContract.Data 表 ， 所 以 需要 使 用 常量 Data.CONTENT_URI 作 为 内 容 URI。 例 如 : 


@Override 
public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) { 
// Choose the proper action 
switch (loaderId) { 
case DETAILS_QUERY_ID: 
// Assigns the selection parameter 
mSelectionArgs[0] = mLookupKey; 
// Starts the query 
CursorLoader mLoader - 
new CursorLoader( 
getActivity(), 
Data.CONTENT URI, 
PROJECTION, 
SELECTION, 
mSelectionArgs, 
SORT. ORDER 


实现 onLoadFinished() 方 法 和 onLoaderReset() 方 法 


实现 onLoadFinished() 方 法 。 当 Contacts Provider 返 回 查询 结果 的 时 候 ，loader 框 架 会 调用 
onLoadFinished() 方 法 。 例 如 : 


public void onLoadFinished(Loader«Cursor» loader, Cursor cursor) { 
switch (loader.getId()) ( 
case DETAILS QUERY ID: 
/* 


* Process the resulting Cursor here. 


break; 


当 |loader 框 架 检测 到 结果 集 Cursor 所 对 应 的 数据 已 经 发 生变 化 的 时 候 ， 会 调用 
onLoaderReset() 方 法 。 这 时 ， 需 要 通过 把 Cursor 设 置 为 null 来 移 除 对 已 经 存在 Cursor 对 象 的 
5] flo GM) > loadertz Rw AAA SK 1 HY Cursors Ko Mi FRA GYM o bite : 


QOverride 
public void onLoaderReset(Loader<Cursor> loader) { 
switch (loader.getId()) ( 


case DETAILS QUERY ID: 
/* 


* If you have current references to the Cursor, 


* remove them here. 


break; 


x MZ ` 米 c 

获取 联系 人 的 特定 类 型 的 信息 

获取 联系 人 的 特定 类 型 的 信息 ， 例 如 所 有 的 email 信 息 ， 跟 获取 联系 人 的 所 有 详细 信息 类 似 。 
下 面 的 内 容 是 在 获取 联系 人 的 所 有 详细 信息 列 出 的 代码 的 基础 上 作出 的 修改 : 

查询 映射 


修改 查询 映射 使 得 能 够 针对 特定 的 数据 类 型 去 获取 列 。 同 时 需要 修改 查询 映射 ， 来 把 在 
ContactsContract.CommonDataKinds 子 类 中 定义 的 列 常量 与 数据 类 型 对 应 起 来 。 


查询 选择 
修改 查询 选择 子 句 去 搜索 特定 类 型 的 MIMETYPE 值 。 
排序 顺序 


由 于 仅仅 搜索 一 种 类 型 的 详细 数据 ， 所 以 不 需要 将 返回 的 Cursor 按 照 Data.MIMETYPE 进 行 分 
组 。 


这 些 修改 将 会 在 下 面 的 小 节 中 详细 描述 。 


设置 查询 映射 


使 用 ContactsContract.CommonDataKinds 的 特定 类 型 子 类 所 定义 的 列 名 称 常量 ， 定 义 我 们 想 
要 获取 的 数据 列 。 如 果 我 们 打算 把 Cursor 绑 定 到 ListView， 确 保 要 获取 1p 列 。 例 如 ， 为 了 
获取 email 数 据 ， 需 要 定义 以 下 数据 映射 : 


private static final String[] PROJECTION = 
{ 
Email. ID, 
Email.ADDRESS, 
Email.TYPE, 
Email.LABEL 


m 


需要 注意 的 是 ， 这 个 查询 映射 使 用 在 ContactsContract.CommonDataKinds.Email 类 中 定义 的 
列 名 称 ， 来 替代 ContactsContract.Data 类 中 定义 的 列 名 称 。 使 用 email 类 型 的 列 名 称 使 得 代码 
更 具 可 读 性 。 


在 查询 映射 中 ， 我 们 也 可 以 使 用 ContactsContract.CommonDataKinds 子 类 所 定义 的 其 他 数据 
列 o 


定义 查询 标准 


根据 我 们 想 要 找 的 特定 联系 人 的 LOOKUP_KEY 和 联系 人 详细 信息 的 Data.MIMETYPE 定 义 一 
个 搜索 表达 式 ， 去 获取 数据 。 把 MIMETYPE 的 值 从 头 到 尾 用 单 引 号 括 住 ， 否 则 的 话 ，content 
provider 将 会 把 这 个 常量 当成 变量 名 而 不 是 字符 串 。 因 为 我 们 使 用 的 是 常量 ， 而 不 是 用 户 提供 
的 值 ， 所 以 这 里 不 需要 使 用 占 位 符 。 例 如 : 


* Defines the selection clause. Search for a lookup key 
* and the Email MIME type 
2 
private static final String SELECTION - 
Data.LOOKUP KEY + " = ?" + 
" AND " + 
Data.MIMETYPE + ”= " + 
"U'" + Email.CONTENT ITEM TYPE + "'"; 
// Defines the array to hold the search criteria 
private String[] mSelectionArgs = { "" }; 


定义 排序 规则 


为 查询 返回 的 Cursor 定 义 一 个 排序 规则 。 由 于 是 检索 特定 的 数据 类 型 ， 删 除根 据 MIMETYPE 
来 排序 的 部 分 。 而 如 果 查 询 的 详细 数据 类 型 包含 子 类 型 ， 可 以 根据 这 个 子 类 型 去 排序 。 例 
如 ， 对 于 email 数 据 ， ae : 


private static final String SORT_ORDER = Email.TYPE + " ASC "; 


使 用 Intent 修 改 联 系 人 信息 
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这 一 课 介绍 如 何 使 用 Intent 去 播 入 一 个 新 的 联系 人 或 者 修改 联系 人 的 数据 。 我 们 不 是 直接 访问 
Contacts Provider， 而 是 通过 Intent 局 动 Contacts 应 用 去 运行 适当 的 Activity。 对 于 这 一 课 中 描 
述 的 数据 修改 行为 ， 如 果 你 向 Intent 发 送 扩 展 的 数据 ， 它 会 自动 填充 进 启 动 的 Activity 页 面 中 。 


使 用 Intent 去 插入 或 者 更 新 一 个 联系 人 是 比较 推荐 的 修改 Contacts Provider 的 做 法 。 原 因 如 
F: 


e 节省 了 我 们 自行 开发 Ul 和 编写 代码 的 时 间 和 精力 。 

e 避免 了 由 于 不 按照 Contacts Provider 的 规则 去 修改 而 产生 的 错误 。 

。 减少 应 用 需要 申请 的 权限 数量 。 因 为 我 们 的 应 用 把 修改 行为 委托 给 已 经 拥有 写 Contacts 
Provider 权 限 的 Contacts 应 用 ， 所 以 我 们 的 应 用 不 需要 再 去 申请 这 个 权限 ，。 


使 用 Intent 持 入 新 的 联系 人 


当 我 们 的 应 用 接收 到 新 的 数据 时 ， 我 们 通常 会 允许 用 户 去 插入 一 个 新 的 联系 人 。 例 如 ， 一 个 
餐馆 评论 应 用 可 以 允许 用 户 在 评论 餐馆 的 时 候 ， 把 这 个 餐馆 添加 为 一 个 联系 人 。 可 以 使 用 
Intent 去 做 这 个 任务 ， 使 用 我 们 拥有 的 尽 可 能 多 的 数据 去 创建 对 应 的 Intent， 然 后 发 送 这 个 
Intent 到 Contacts 应 用 。 


使 用 Contacts 应 用 去 插入 一 个 联系 人 将 会 向 Contacts Provider 中 的 
ContactsContract.RawContacts 表 中 插入 一 个 原始 联系 人 。 必 要 的 情况 下 ， 在 创建 原始 联系 
人 的 时 候 ，Contacts 应 用 将 会 提示 用 户 选择 账户 类 型 和 要 使 用 的 账户 。 如 果 联 系 人 已 经 存 
在 ，Contacts 应 用 也 会 告知 用 户 。 用 户 将 会 有 取消 插入 的 选项 ， 在 这 种 情况 下 不 会 有 联系 人 
被 创建 。 想 要 知道 更 多 关于 原始 联系 人 的 信息 ， 请 参阅 Contacts Provider 的 API 指 导 。 


创建 一 个 Intent 


利用 Intents.Insert.ACTION 创 建 一 个 新 的 Intent 对 象 ， 并 设置 其 MIME 类 型 
为 RawContacts.CONTENT_TYPE。 例 如 : 


// Creates a new Intent to insert a contact 

Intent intent - new Intent(Intents.Insert.ACTION); 

// Sets the MIME type to match the Contacts Provider 
intent.setType(ContactsContract.RawContacts.CONTENT TYPE); 


如 果 我 们 已 经 获得 了 此 联系 人 的 详细 信息 ， 比 如 说 电话 号 码 或 者 email 地 址 ， 那 么 我 们 可 以 把 
它们 作为 扩展 数据 添加 到 Intent 中 。 对 于 键 值 ， 需 要 使 用 Intents.Insert 中 对 应 的 常量 
Contacts 应 用 将 会 在 插入 界面 显示 这 些 数据 ， 以 便 用 户 作 进一步 的 数据 编辑 和 数据 添加 。 


/* Assumes EditText fields in your UI contain an email address 
* and a phone number. 


*/ 
private EditText mEmailAddress - (EditText) findViewById(R.id.email); 
private EditText mPhoneNumber - (EditText) findViewById(R.id.phone); 


/* 
* Inserts new data into the Intent. This data is passed to the 
* contacts app's Insert screen 
i 
// Inserts an email address 
intent.putExtra(Intents.Insert.EMAIL, mEmailAddress.getText()) 
/* 
* In this example, sets the email type to be a work email. 
* You can set other email types as necessary. 
iA 
.putExtra(Intents.Insert.EMAIL TYPE, CommonDataKinds.Email.TYPE WORK) 
// Inserts a phone number 
.putExtra(Intents.Insert.PHONE, mPhoneNumber.getText()) 
/* 
* In this example, sets the phone type to be a work phone. 
* You can set other phone types as necessary. 
i 
.putExtra(Intents.Insert.PHONE TYPE, Phone.TYPE WORK); 
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/* Sends the Intent 
sy 
startActivity(intent); 


这 个 调用 将 会 打开 Contacts 应 用 的 界面 ， 并 允许 用 户 进入 一 个 新 的 联系 人 。 这 个 联系 人 的 账 
户 类 型 和 账户 名 字 列 在 屏幕 的 上 方 。 一 旦 用 户 输 入 数据 并 点 击 确定 ，Contacts 应 用 的 联系 人 
列表 则 会 显示 出 来 。 用 户 可 以 点 击 Back 键 返回 到 我 们 自己 创建 的 应 用 。 


使 用 Intent 编 辑 已 经 存在 的 联系 人 


如 果 用 户 已 经 选择 了 一 个 感 兴趣 的 联系 人 ， 使 用 Intent 去 编辑 这 个 已 存在 的 联系 人 会 很 有 用 。 
例如 ， 一 个 用 来 查找 拥有 邮政 地 址 但 是 缺少 邮政 编码 的 联系 人 的 应 用 ， 可 以 给 用 户 提供 查找 
邮政 编码 的 选项 ， 然 后 把 找到 的 邮政 编码 添加 到 这 个 联系 人 中 。 


使 用 Intent 编 辑 已 经 存在 的 联系 人 ， 同 插入 一 个 联系 人 的 步骤 类 似 。 像 前 面 介 绍 的 使 用 Intent 
插入 新 的 联系 人 创建 一 个 Intent， 但 是 需要 给 这 个 Intent 添 加 对 应 联系 人 的 
Contacts.CONTENT_LOOKUP_URI 和 MIME 类 型 Contacts.CONTENT ITEM TYPE ° RA 
要 使 用 已 经 拥有 的 详情 信息 编辑 这 个 联系 人 ， 我 们 需要 把 这 些 数据 放 到 Intent 的 扩展 数据 中 。 
同时 注意 有 些 列 是 不 能 使 用 Intent 编 辑 的 ， 这 些 不 可 编辑 的 列 在 ContactsContract.Contacts 4 
要 部 分 "Update” 标 题 下 有 列 出 。 


最 后 ， 发 送 这 个 Intent。Contacts 应 用 会 显示 一 个 编辑 界面 作为 回应 。 当 用 户 编 辑 完 成 并 保 
存 ，Contacts 应 用 会 显示 一 个 联系 人 列表 。 当 用 户 点 击 Back， 我 们 自己 的 应 用 会 出 现 。 


创建 Intent 


为 了 能 够 编辑 一 个 联系 人 ， 需 要 调用 Intent(action) 去 创建 一 个 拥有 ACTION_EDIT 行 为 的 
Intent。 调 用 setDataAndType() 去 设置 这 个 Intent 要 编辑 的 联系 人 的 
Contacts.CONTENT_LOOKUP_URI#*MIME # #! Contacts. CONTENT_ITEM_TYPE 。 因 为 调 
用 setType() 会 重 写 Intent 当 前 的 数据 ， 所 以 我 们 必须 同时 设置 数据 和 MIME 类 型 。 


为 了 得 到 联系 人 的 Contacts.CONTENT_LOOKUP _URI， 需 要 调用 Contacts.getLookupUrikid， 
Ilookupkey) 方 法 ， 该 方法 的 参数 分 别 是 联系 人 的 Contacts. ID 和 Contacts.LOOKUP KEY ° 


以 下 的 代码 片段 展示 了 如 何 创 建 这 个 Intent : 


// The Cursor that contains the Contact row 
public Cursor mCursor; 
// The index of the lookup key column in the cursor 
public int mLookupKeyIndex; 
// The index of the contact's TD value 
public int mIdIndex; 
// The lookup key from the Cursor 
public String mCurrentLookupKey; 
// The ID value from the Cursor 
public long mCurrentId; 





// A content URI pointing to the contact 
Uri mSelectedContactUri; 


/* 
* Once the user has selected a contact to edit, 
* this gets the contact's lookup key and _ID values from the 
* cursor and creates the necessary URI. 
ud 
// Gets the lookup key column index 
mLookupKeyIndex - mCursor.getColumnIndex(Contacts.LOOKUP KEY); 
// Gets the lookup key value 
mCurrentLookupKey = mCursor.getString(mLookupKeyIndex); 
// Gets the ID column index 
mIdIndex - mCursor.getColumnIndex(Contacts. ID); 
mCurrentId - mCursor.getLong(mIdIndex); 
mSelectedContactUri - 
Contacts.getLookupUri(mCurrentId, mCurrentLookupKey); 


// Creates a new Intent to edit a contact 
Intent editIntent - new Intent(Intent.ACTION EDIT); 
Jus 
* Sets the contact URI to edit, and the data type that the 
* Intent must match 
o7 
editIntent.setDataAndType(mSelectedContactUri,Contacts.CONTENT ITEM TYPE); 


添加 导航 标记 


在 Android 4.0 (API 版 本 14) 和 更 高 的 版 本 ，Contacts 应 用 中 的 一 个 问题 会 导致 错误 的 页 面 导 
航 。 我 们 的 应 用 发 送 一 个 编辑 联系 人 的 Intent 到 Contacts 应 用 ， 用 户 编辑 并 保存 这 个 联系 人 ， 
当 用 户 点 击 Back 键 的 时 候 会 看 到 联系 人 列表 页 面 。 用 户 需 要 点 击 最 近 使 用 的 应 用 ， 然 后 选择 
我 们 的 应 用 ， 才 能 返回 到 我 们 自己 的 应 用 。 


要 在 Android 4.0.3 (API 版 本 15) 及 以 后 的 版 本 解决 此 问题 ， 需 要 添 

加 finishActivityonSaveCompleted 扩展 数据 参数 到 这 个 Intent， 并 将 它 的 值 设 置 为 true » 
Android 4.0 之 前 的 版 本 也 能 够 接受 这 个 参数 ， 但 是 不 起 作用 。 为 了 设置 扩展 数据 ， 请 按照 以 
下 方式 去 做 : 


// Sets the special extended data for navigation 
editIntent.putExtra("finishActivityOnSaveCompleted", true); 


添加 其 他 的 扩展 数据 


inteni we 外 的 扩展 数据 ， 需 要 调用 putExtra()。 可 以 为 常见 的 联系 人 数据 字段 添加 扩展 数 
据 ， 这 些 常见 字段 的 key 值 可 以 从 Intents.Insert 文档 中 查 到 。 记 住 
ContactsContract.Contacts 表 中 有 些 列 是 不 能 编辑 的 ， 这 些 列 在 ContactsContract.Contacts 的 
摘要 部 分 “Update” 标 题 下 有 列 出 。 


发 送 Intent 
最 后 ， 发 送 我 们 已 经 构建 好 的 Intent。 例 如 : 


// Sends the Intent 
startActivity(editIntent); 


使 用 Intent 让 用 户 去 选择 是 插入 还 是 编辑 联系 人 


我 们 可 以 通过 发 送 带 有 ACTION INSERT OR EDIT 行为 的 Intent， 让 用 户 去 选择 是 插入 联系 人 还 是 
编辑 已 有 的 联系 人 。 例 如 ， 一 个 email 客 户 端 应 用 会 允许 用 户 添加 一 个 收 件 地 址 到 新 的 联系 

人 ， 或 者 仅仅 作为 额外 的 邮件 地 址 添加 到 已 有 的 联系 人 。 需 要 为 这 个 Intent 设 置 MIME 类 型 
Contacts.CONTENT ITEM TYPE ， 但 是 不 需要 设置 数据 URI。 


当 我 们 发 送 这 个 Intent 后 ，Contacts 应 用 会 展示 一 个 联系 人 列表 。 用 户 可 以 选择 是 插入 一 个 新 
的 联系 人 还 是 挑选 一 个 存在 的 联系 人 去 编辑 。 任 何 添加 到 Intent 中 的 扩展 数据 字段 都 会 十 充 在 
bid o GA 可 以 使 用 任何 在 Intents.Insert 中 指定 的 的 key 值 。 以 下 的 代码 片段 展示 了 如 何 构 
建 和 发 送 这 个 Intent : 


// Creates a new Intent to insert or edit a contact 
Intent intentInsertEdit - new Intent(Intent.ACTION INSERT OR EDIT); 
// Sets the MIME type 
intentInsertEdit.setType(Contacts.CONTENT ITEM TYPE); 
// Add code here to insert extended data, if desired 


// Sends the Intent with an request ID 
startActivity(intentInsertEdit); 


显示 联系 人 头像 
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这 一 课 展示 了 如 何在 我 们 的 应 用 界面 上 添加 一 个 QuickContactBadge， 以 及 如 何 为 它 绑 定 数 
据 。QuickContactBadge 是 一 个 在 初始 情况 下 显示 联系 人 缩 略 图 头像 的 widget。 尽 管 我 们 可 
以 使 用 任何 Bitmap 作 为 缩 略 图 头像 ， 但 是 我 们 通常 会 使 用 从 联系 人 照片 缩 略 图 中 解码 出 来 的 
Bitmap ° 


这 个 小 的 图 片 是 一 个 控件 ， 当 用 户 点 击 它 时 ，QuickContactBadge 会 展开 一 个 包含 以 下 内 容 的 
对 话 框 : 


e 一 个 大 的 联系 人 头像 
与 这 个 联系 人 关联 的 大 的 头像 ， 如 果 此 人 没有 设置 头像 ， 则 显 留 的 图 案 。 
e 应 用 程序 图 标 


根据 联系 人 详情 数据 ， 显 示 每 一 个 能 够 被 手机 中 的 应 用 所 处 理 的 数据 的 图 标 。 例 如 ， 如 
果 联 系 人 的 数据 包含 一 个 或 多 个 email 地 址 ， 就 会 显示 email 应 用 的 图 标 。 当 用 户 点 击 这 个 
图 标的 时 候 ， 这 个 联系 人 所 有 的 email 地 址 都 会 显示 出 来 。 当 用 户 点 击 其 中 一 个 email 地 址 
时 ，email 应 用 将 会 显示 一 个 界面 ， 让 用 户 为 选中 的 地 址 撰写 邮件 。 


QuickContactBadge 视 图 提供 了 对 联系 人 数据 的 即时 访问 ， 是 一 种 Ss 系 人 沟通 的 快捷 方式 。 
用 户 不 用 查询 一 个 联系 人 ， 查 找 并 复制 信息 ， ba 息 粘 贴 到 合适 的 应 用 中 。 他 们 可 以 点 
击 QuickContactBadge， 选 择 他 们 想 要 的 沟通 方式 ， 然 后 直接 把 信息 发 送 给 合适 的 应 用 中 。 


Asta — 4 QuickContactBadge 2 A 


为 了 添加 一 个 QuickContactBadge 视 图 ， 需 要 在 布局 文件 中 插入 一 个 QuickContactBadge。 例 
如 : 


«RelativeLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:layout width-"match parent" 
android: layout_height="match_parent"> 


<QuickContactBadge 
android: id=@+id/quickbadge 
android: layout_height="wrap_content" 
android: layout_width="wrap_content" 
android: scaleType="centerCrop"/> 


</RelativeLayout> 


获取 Contacts Provider £4 242 


为 了 能 在 QuickContactBadge 中 显示 联系 人 人， 我们 需要 这 个 联系 人 的 内 容 URI 和 显示 头像 的 
Bitmap。 我 们 可 以 从 在 Contacts Provider 中 获取 到 的 数据 列 中 生成 这 两 个 数据 。 需 要 指定 
些 列 作为 查询 映射 去 把 数据 加 载 到 Cursor 中 。 


ps 


对 于 Android 3.0 (API 版 本 为 11) 以 及 以 后 的 版 本 ， 需 要 在 查询 映射 中 添加 以 下 列 : 


e Contacts. ID 
e Contacts.L OOKUP KEY 
e Contacts.PHOTO THUMBNAIL URI 


xt T Android 2.3.3 (API 版 本 为 10) 以 及 之 前 的 版 本 ， 则 使 用 以 下 列 : 


e Contacts. ID 
e Contacts. OOKUP KEY 


这 一 课 的 剩余 部 分 假设 你 已 经 获取 到 了 包含 这 些 以 及 其 他 你 可 能 选择 的 数据 列 的 Cursor 对 
象 。 想 要 学 习 如 何 获取 这 些 列 对 象 的 Cursor， 请 参阅 课程 获取 联系 人 列表 。 


设置 联系 人 URI 和 缩 略 图 
一 旦 我 们 已 经 拥有 了 所 需 的 数据 列 ， 那 么 我 们 就 可 以 为 QuickContactBadge 视 图 绑 定 数据 了 。 


设置 联系 人 URI 


为 了 设置 联系 人 URI， 需 要 调用 getLookupUri(id, lookupKey) 去 获取 
CONTENT_LOOKUP_URI， 然 后 调用 assignContactUri()) 去 为 QuickContactBadge 设 置 对 应 
的 联系 人 。 例 如 : 


// The Cursor that contains contact rows 

Cursor mCursor; 

// The index of the ID column in the Cursor 

int mlIdColumn; 

// The index of the LOOKUP KEY column in the Cursor 
int mLookupKeyColumn; 

// A content URI for the desired contact 

Uri mContactUri; 

// A handle to the QuickContactBadge view 
QuickContactBadge mBadge; 


mBadge - (QuickContactBadge) findViewById(R.id.quickbadge); 
/* 
* Insert code here to move to the desired cursor row 
EYA 
// Gets the _ID column index 
mIdColumn = mCursor.getColumnIndex(Contacts. ID); 
// Gets the LOOKUP KEY index 
mLookupKeyColumn - mCursor.getColumnIndex(Contacts.LOOKUP KEY); 
// Gets a content URI for the contact 
mContactUri = 
Contacts.getLookupUri( 
mCursor.getLong(mIdColumn), 
mCursor.getString(mLookupKeyColumn) 
); 


mBadge.assignContactUri(mContactUri); 


当 用 户 点 击 QuickContactBadge 图 标的 时 候 ， 这 个 联系 人 的 详细 信息 将 会 自动 展现 在 对 话 框 
中 。 


设置 联系 人 照片 的 缩 略图 


为 QuickContactBadge 设 置 联系 人 URI 并 不 会 自动 加 载 联系 人 的 缩 略图 照片 。 为 了 加 载 联 系 人 
有 照片， 需要 从 联系 人 的 Cursor 对 象 的 一 行 数据 中 获取 照片 的 URI， 使 用 这 个 URI 去 打开 包含 压 
缩 的 缩 略 图 文件 ， 并 把 这 个 文件 读 到 Bitmap 对 象 中 。 


Note : PHOTO_THUMBNAIL_URI 这 一 列 在 Android 3.0 之 前 的 版 本 是 不 存在 的 。 对 于 这 
些 版 本 ， 我 们 必须 从 Contacts.Photo 表 中 获取 照片 的 URI 。 


首先 ， 为 包含 Contacts. ID 和 Contacts.LOOKUP _ KEY 的 Cursor 数 据 列 设置 对 应 的 变量 ， 这 在 
之 前 已 经 有 描述 : 


// The column in which to find the thumbnail ID 
int mThumbnailColumn; 
ES 
* The thumbnail URI, expressed as a String. 
* Contacts Provider stores URIs as String values. 
wh 
String mThumbnailuUri; 


/* 
* Gets the photo thumbnail column index if 
* platform version »- Honeycomb 
4 
if (Build.VERSION.SDK INT >= Build.VERSION CODES.HONEYCOMB) { 
mThumbnailColumn - 
mCursor.getColumnIndex(Contacts.PHOTO THUMBNAIL URI); 
// Otherwise, sets the thumbnail column to the ID column 
else { 
mThumbnailColumn = mIdColumn; 
} 
/* 
* Assuming the current Cursor position is the contact you want, 
* gets the thumbnail ID 
ef 
mThumbnailUri = mCursor.getString(mThumbnailColumn) ; 


定义 一 个 方法 ， 使 用 与 这 个 联系 人 的 照片 有 关 的 数据 和 目标 视图 的 尺寸 作为 参数 ， 返 回 一 个 
尺寸 合适 的 缩 略 图 Bitmap 对 象 。 下 面 先 构建 一 个 指向 这 个 缩 略 图 的 URI : 


yee 
* Load a contact photo thumbnail and return it as a Bitmap, 
* resizing the image to the provided image dimensions as needed. 
* @param photoData photo ID Prior to Honeycomb, the contact's _ID value. 
* For Honeycomb and later, the value of PHOTO THUMBNAIL URI. 
* Qreturn A thumbnail Bitmap, sized to the provided width and height. 
* Returns null if the thumbnail is not found. 
sh 
private Bitmap loadContactPhotoThumbnail(String photoData) { 
// Creates an asset file descriptor for the thumbnail file. 
AssetFileDescriptor afd - null; 
// try-catch block for file not found 
try { 
// Creates a holder for the URI. 
Uri thumbUri; 
// If Android 3.0 or later 
if (Build.VERSION.SDK INT 
D 
Build.VERSION CODES.HONEYCOMB) { 
// Sets the URI from the incoming PHOTO THUMBNAIL URI 
thumbUri - Uri.parse(photoData); 
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} else { 
// Prior to Android 3.0, constructs a photo Uri using _ID 
/* 
* Creates a contact URI from the Contacts content URI 
* incoming photoData ( ID) 
zy 
final Uri contactUri = Uri.withAppendedPath( 
Contacts.CONTENT URI, photoData); 
/* 
* Creates a photo URI by appending the content URI of 
* Contacts.Photo. 
yf 
thumbUri = 
Uri.withAppendedPath( 
contactUri, Photo.CONTENT DIRECTORY); 


/* 
* Retrieves an AssetFileDescriptor object for the thumbnail 
SURG 
* using ContentResolver.openAssetFileDescriptor 
sh 

afd = getActivity().getContentResolver(). 

openAssetFileDescriptor(thumbUri, "r"); 

/* 

* Gets a file descriptor from the asset file descriptor. 
* This object can be used across processes. 
E 

FileDescriptor fileDescriptor - afd.getFileDescriptor(); 

// Decode the photo file and return the result as a Bitmap 

// If the file descriptor is valid 

if (fileDescriptor != null) { 

// Decodes the bitmap 
return BitmapFactory.decodeFileDescriptor ( 
fileDescriptor, null, null); 
} 
// If the fale isn't found 
} catch (FileNotFoundException e) { 


/* 
* Handle file not found errors 
27A 
} 
// In all cases, close the asset file descriptor 
} finally { 
if (afd != null) ( 
try { 
afd.close(); 
} catch (IOException e) {} 
} 
} 


return null; 
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在 代码 中 调用 loadContactPhotoThumbnail() 去 获取 缩 略图 Bitmap 对 象 ， 使 用 获取 的 Bitmap 对 
象 去 设置 QuickContactBadge 头 像 缩 略图 。 


* Decodes the thumbnail file to a Bitmap. 
uf 
Bitmap mThumbnail = 
loadContactPhotoThumbnail(mThumbnailUri); 
/* 
* Sets the image in the QuickContactBadge 
* QuickContactBadge inherits from ImageView, so 
nA 
mBadge.setImageBitmap(mThumbnail); 


jc QuickContactBadge $7» #1 ListView 


QuickContactBadge 对 于 一 个 展示 联系 人 列表 的 ListView 来 说 是 一 个 非常 有 用 的 添加 功能 。 使 
用 QuickContactBadge 去 为 每 一 个 联系 人 显示 一 个 缩 略 图 ， 当 用 户 点 击 这 个 缩 略 图 时 ， 
QuickContactBadge 对 话 框 将 会 显示 。 


A ListView “22 QuickContactBadge 


首先 ， 在 列表 项 布局 文件 中 添加 QuickContactBadge 视 图 元 素 。 例 如 ， 如 果 我 们 想 为 获取 到 的 
每 一 个 联系 人 显示 QuickContactBadge 和 名 字 ， 把 以 下 的 XML 内 容 放 到 对 应 的 布局 文件 中 : 


«RelativeLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android: layout_width="match_parent" 
android: layout_height="wrap_content"> 

<QuickContactBadge 
android: id="@+tid/quickcontact" 
android: layout_height="wrap_content" 
android: layout_width="wrap_content" 
android: scaleType="centerCrop"/> 
<TextView android: id="@+id/displayname" 
android: layout_width="match_parent" 
android: layout_height="wrap_content" 
android: layout_toRightOf="@+id/quickcontact" 
android:gravity-"center vertical" 
android:layout alignParentRight-"true" 
android: layout_alignParentTop="true"/> 
</RelativeLayout> 


在 以 下 的 章节 中 ， 这 个 文件 被 称 为 contact item layout.xml ° 


设置 自 定义 的 CursorAdapter 


定义 一 个 继承 自 CursorAdapter 的 adapter 来 将 CursorAdapter 绑 定 到 一 个 包含 
QuickContactBadge 的 ListView 中 。 这 种 方式 允许 我 们 在 绑 定 数据 到 QuickContactBadge 之 前 
对 Cursor 中 的 数据 进行 处 理 。 同 时 也 能 将 多 个 Cursor 中 的 列 绑 定 到 QuickContactBadge。 而 使 
用 普通 的 CursorAdapter 是 不 能 完成 这 些 操作 的 。 


我 们 定义 的 CursorAdapter 的 子 类 必须 重 写 以 下 方法 : 
e CursorAdapter.newView() 


填充 一 个 View 对 象 去 持 有 列表 项 布局 。 在 重 写 这 个 方法 的 过 程 中 ， 需 要 保存 这 个 布局 的 
子 View 的 handles ， 包 括 QuickContactBadge 的 handles。 通 过 采用 这 种 方法 ， 避 免 了 每 
次 在 填充 新 的 布局 时 都 去 获取 子 View 的 handles。 


我 们 必须 重 写 这 个 方法 以 便 能 够 获取 每 个 子 View 对 象 的 handles。 这 种 方法 允许 我 们 控制 
这 些 子 View 对 象 在 CursorAdapter.bindView() 方 法 中 的 绑 定 。 


e CursorAdapter.bindView() 


将 数据 从 当前 Cursor 行 绑 定 到 列表 项 布局 的 子 View 对 象 中 。 必 须 重 写 这 个 方法 以 便 能 够 
将 联系 人 的 URI 和 缩 略 图 信息 绑 定 到 QuickContactBadge。 这 个 方法 的 默认 实现 仅仅 允许 
在 数据 列 和 View 之 间 的 一 对 一 映射 。 


以 下 的 代码 片段 是 一 个 包含 了 自 定 义 CursorAdapter 子 类 的 例子 。 


定义 自 定义 的 列表 Adapter 
定义 CursorAdapter 的 子 类 包括 编写 这 个 类 的 构造 方法 ， 以 及 重 写 newView() 和 bindView(): 


private class ContactsAdapter extends CursorAdapter { 
private LayoutInflater mInflater; 


public ContactsAdapter(Context context) { 
super(context, null, 0); 


/* 
* Gets an inflater that can instantiate 
* the ListView layout from the file. 
dA 

mInflater - LayoutInflater.from(context); 


} 


J** 

* Defines a class that hold resource IDs of each item layout 
* row to prevent having to look them up each time data is 

* bound to a row. 


private class ViewHolder { 
TextView displayname; 
QuickContactBadge quickcontact; 


@Override 
public View newView( 
Context context, 
Cursor cursor, 
ViewGroup viewGroup) { 
/* Inflates the item layout. Stores resource IDs in a 
* in a ViewHolder class to prevent having to look 
* them up each time bindView() is called. 
$5 
final View itemView - 
mInflater.inflate( 
R.layout.contact list layout, 
viewGroup, 
false 
) ; 
final ViewHolder holder = new ViewHolder(); 
holder.displayname = 
(TextView) view.findViewById(R.id.displayname); 
holder.quickcontact - 
(QuickContactBadge) 
view.findViewById(R.id.quickcontact); 
view.setTag(holder); 


return view; 


QOverride 
public void bindView( 
View view, 
Context context, 
Cursor cursor) { 
final ViewHolder holder = (ViewHolder) view.getTag(); 
final String photoData = 
cursor .getString(mPhotoDataIndex) ; 
final String displayName = 
cursor .getString(mDisplayNameIndex) ; 


// Sets the display name in the layout 
holder.displayname = cursor.getString(mDisplayNameIndex); 


/* 
* Generates a contact URI for the QuickContactBadge. 
27 
final Uri contactUri - Contacts.getLookupUri( 
cursor.getLong(mIdIndex), 
cursor.getString(mLookupKeyIndex)); 
holder.quickcontact.assignContactUri(contactUri); 
String photoData = cursor.getString(mPhotoDataIndex); 





/* 
* Decodes the thumbnail file to a Bitmap. 
* The method loadContactPhotoThumbnail() is defined 
* in the section "Set the Contact URI and Thumbnail" 
27] 

Bitmap thumbnailBitmap - 

loadContactPhotoThumbnail(photoData); 

/* 
* Sets the image in the QuickContactBadge 
* QuickContactBadge inherits from ImageView 
Lyf 

holder .quickcontact.setImageBitmap(thumbnailBitmap) ; 


设置 变量 
在 代码 中 ， 设 置 相 关 变 量 ， 添 加 一 个 包括 必须 数据 列 的 Cursor © 


Note : 以 下 的 代码 片段 使 用 了 方法 loadcontactPhotoThumbnail() 
系 人 URI 和 缩 略 图 那 一 节 中 定义 的 。 


例如 : 


public class ContactsFragment extends Fragment implements 
LoaderManager .LoaderCallbacks<Cursor> { 


// Defines a ListView 

private ListView mListView; 

// Defines a ContactsAdapter 
private ContactsAdapter mAdapter; 


// Defines a Cursor to contain the retrieved data 
private Cursor mCursor; 
/* 
* Defines a projection based on platform version. This ensures 
* that you retrieve the correct columns. 
n 
private static final String[] PROJECTION - 
{ 
Contacts._ID, 
Contacts.LOOKUP KEY, 
(Build.VERSION.SDK INT >= 
Build.VERSION CODES.HONEYCOMB) ? 
Contacts.DISPLAY NAME PRIMARY : 
Contacts.DISPLAY NAME 
(Build.VERSION.SDK INT >= 
Build.VERSION CODES.HONEYCOMB) ? 
Contacts.PHOTO THUMBNAIL ID 
/* 


， 这 个 方法 是 在 设置 联 


* Although it's not necessary to include the 
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* column twice, this keeps the number of 
* columns the same regardless of version 
v 

Contacts ID 


}; 
/* 
* As a shortcut, defines constants for the 
column indexes in the Cursor. The index is 
Q-based and always matches the column order 
* in the projection. 
E 
// Column index of the _ID column 
private int mIdIndex - 0; 
// Column index of the LOOKUP KEY column 
private int mLookupKeyIndex = 1; 
// Column index of the display name column 
private int mDisplayNameIndex - 3; 
/* 
* Column index of the photo data column. 
* It's PHOTO THUMBNAIL URI for Honeycomb and later, 
* and ID for previous versions. 
i 
private int mPhotoDataIndex = 
Build.VERSION.SDK INT »- Build.VERSION CODES.HONEYCOMB ? 


oe 
0; 
iX a ListView 


在 Fragment.onCreate()) 方 法 中 ， 实 例 化 自 定义 的 adapter 对 象 ， 获 得 一 个 ListView 的 handle。 


@Override 
public void onCreate(Bundle savedInstanceState) { 


/* 
* Instantiates the subclass of 
* CursorAdapter 
i7 
ContactsAdapter mContactsAdapter = 
new ContactsAdapter(getActivity()); 
/* 
* Gets a handle to the ListView in the file 
* contact list layout.xml 
x 
mListView - (ListView) findViewById(R.layout.contact list layout); 
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在 onActivityCreated()) 方 法 中 ， 将 ContactsAdapter 绑 定 到 ListView ° 


@Override 
public void onActivityCreated(Bundle savedInstanceState) { 


// Sets up the adapter for the ListView 
mListView.setAdapter(mAdapter); 


当 获 取 到 一 个 包含 联系 人 数据 的 Cursor 时 (通常 在 onLoadFinished() 的 时 候 ) ， 调 用 
swapCursor() 把 Cursor 中 的 数据 绑 定 到 ListView。 这 将 会 为 联系 人 列表 中 的 每 一 项 都 显示 一 个 
QuickContactBadge ° 


public void onLoadFinished(Loader«Cursor» loader, Cursor cursor) { 
// When the loader has completed, swap the cursor into the adapter. 


mContactsAdapter.swapCursor(cursor); 


当 我 们 使 用 CursorAdapter 或 其 子 类 中 将 Cursor 中 的 数据 绑 定 到 ListView， 并 且 使 用 了 
CursorLoader 去 加 载 Cursor 数 据 时 ， 记 得 要 在 onLoaderReset() 方 法 的 实现 中 清理 对 Cursor 对 
象 的 引用 。 例 如 : 


@Override 

public void onLoaderReset(Loader<Cursor> loader) { 
// Removes remaining reference to the previous Cursor 
mContactsAdapter .swapCursor (null); 


Android 位 置信 息 


编写 :penkzhou - /$ x-:http://developer.android.com/training/location/index.html 


位 置 感知 是 移动 应 用 一 个 独特 的 功能 。 用 户 去 到 哪里 都 会 带 着 他 们 的 移动 设备 ， 而 将 位 置 感 
知 功 能 添加 到 我 们 的 应 用 里 ， 可 以 让 用 户 有 更 加 丨 实 的 情境 体验 。 位 置 服务 API| 集 成 在 Google 
Play 服 务 里 面 ， 这 便于 我 们 将 自动 位 置 跟踪 、 地 理 围 栏 和 用 户 活 动 识别 等 位 置 感知 功能 添加 
到 我 们 的 应 用 当中 。 


我 们 喜欢 用 Google Play services location APls 胜 过 Android framework location APls 
(android.location) 来 给 我 们 的 应 用 添加 位 置 感知 功能 。 如 果 你 现在 正在 使 用 Android 
framework location APls， 我 们 强烈 建议 你 尽 可 能 切换 到 Google Play services location 
APIs ° 


这 个 课程 介绍 如 何 使 用 Google Play services location APls 来 获取 当前 位 置 、 周 期 性 地 更 新 位 
置 以 及 查找 地 址 。 创 建 并 监视 地 理 围栏 以 及 探测 用 户 的 活动 。 这 个 课程 包括 示例 应 用 和 代码 
片段 ， 你 可 以 利用 这 些 资 源 作 为 添加 位 置 感 知 到 你 的 应 用 的 基础 。 


Note : 因为 这 个 课程 基于 Google Play services client library， 所 以 在 使 用 这 些 示例 应 用 


和 代码 段 之 前 确保 你 安装 了 最 新 版 本 的 Google Play services client library ° 284 3 Je 


何 安装 最 新 版 的 client library， 请 参考 安装 Google Play services 向 导 。 


Lessons 


。 获取 最 后 可 知 位 置 


学 习 如 何 获 取 Android 设 备 的 最 后 可 知 位 置 。 通 常 Android 设 备 的 最 后 可 知 位 置 相 当 于 用 户 
的 当前 位 置 。 


e 接收 位 置 更 新 

学 习 如 何 请 求 和 接收 周期 性 的 位 置 更 新 。 
e 显示 位 置地 址 

学 习 如 何 将 一 个 位 置 的 经 纬度 转化 成 一 个 地 址 〈 反 向 地 理 编码 ) 。 
e 创建 和 监视 地 理 围栏 


学 习 如 何 将 一 个 或 多 个 地 理 区 域 定义 成 一 个 兴趣 位 置 集合 ， 称 为 地 理 围 栏 。 学 习 如 何 探 
测 用 户 靠 近 或 者 进入 地 理 围栏 事件 。 


Android 位 置信 息 
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获取 最 后 可 知 位 置 


编写 :penkzhou - 原文 :http://developer.android.com/training/location/retrieve- 
current.html 


使 用 Google Play services location APls， 我 们 的 应 用 可 以 请 求 获得 用 户 设备 的 最 后 可 知 位 
置 。 大 多 数 情况 下 ， 我 们 会 对 用 户 的 当前 位 置 比 较 感 兴趣 。 而 通常 用 户 的 当前 位 置 相 当 于 设 
备 的 最 后 可 知 位 置 。 


特别 地 ， 使 用 fused location provider 来 获取 设备 的 最 后 可 知 位 置 。fused location providerz& 
Google Play services location APls 中 的 一 个 。 它 处 理 基 本 定位 技术 并 提供 一 个 简单 的 API， 
使 得 我 们 可 以 指定 高 水 平 的 需求 ， 如 高 精度 或 者 低 功 耗 。 同 时 它 优 化 了 设备 的 耗 电 情况 。 


这 节 课 介绍 如 何 通过 使 用 fused location provider 的 getLastLocation()) 方 法 为 设备 的 位 置 构造 


一 个 单一 请 求 。 


安装 Google Play Services 


为 了 访问 fused location provider， 我 们 的 应 用 开发 工程 必须 包括 Google Play services。 通 过 
SDK Manager 下 载 和 安装 Google Play services 组 件 ， 添 加 相关 的 库 到 我 们 的 工程 。 更 详细 的 
介绍 ， 请 看 Setting Up Google Play Services。 


确定 应 用 的 权限 


使 用 位 置 服务 的 应 用 必须 请 求 用 户 位 置 权 限 。Android 拥 有 两 种 位 置 权 

IK : ACCESS COARSE LOCATION 和 ACCESS _ FINE_LOCATION。 我 们 选择 的 权限 决定 
API 返 回 的 位 置信 息 的 精度 。 如 果 我 们 选择 了 ACCESS COARSE LOCATION ，API 返 回 的 位 
置信 息 的 精确 度 大 体 相 当 于 一 个 城市 街区 。 


这 节 课 只 要 求 粗 略 的 定位 。 在 我 们 应 用 的 manifest 文 件 中 ， 用 uses-permission 节点 请 求 这 个 


权限 ， 如 下 所 示 : 


«manifest xmlns:android-"http://schemas.android.com/apk/res/android" 
package="com.google.android.gms.location.sample.basiclocationsample" > 


<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> 
</manifest> 


连接 Google Play Services 


为 了 连接 到 API， 我 们 需要 创建 一 个 Google Play services API 客 户 端 实 例 。 关 于 使 用 这 个 客户 
端的 更 详细 的 介绍 ， 请 看 Accessing Google APIs ° 


在 我 们 的 activity 的 onCreate()) 方 法 中 ， 用 GoogleApiClient.Builder 创 建 一 个 Google API Client 
实例 。 使 用 这 个 builder 添 加 LocationServices API » 


实例 应 用 定义 了 一 个 buildGoogleApiclient() 方法 ， 这 个 方法 在 activity 的 onCreate() 方 法 中 被 
调用 。 buildGoogleApiclient() 方法 包括 下 面 的 代码 。 


protected synchronized void buildGoogleApiClient() { 
mGoogleApiClient - new GoogleApiClient.Builder(this) 
.addConnectionCallbacks(this) 
.addOnConnectionFailedListener(this) 
.addApi(LocationServices.API) 
.build(); 


获取 最 后 可 知 位 置 


— € #1414 Google Play services 和 |ocation services API 和 连接 完 成 后 ， 我 们 就 可 以 获取 用 户 设 
备 的 最 后 可 知 位 置 。 当 我 们 的 应 用 连接 到 这 些 服务 之 后 ， 我 们 可 以 用 fused location provider 
的 getLastLocation()) 方 法 来 获取 设备 的 位 置 。 调 用 这 个 方法 返回 的 定位 精确 度 是 由 我 们 在 应 
用 的 manifest 文 件 里 添加 的 权限 决定 的 ， 如 本 文 的 确定 应 用 的 权限 部 分 描述 的 内 容 一 样 。 


为 了 请 求 最 后 可 知 位 置 ， 调 用 getLastLocation()) 方 法 ， 并 将 我 们 创建 的 GoogleApiClient 对 象 
的 实例 传 给 该 方法 。 在 Google API Client 提 供 的 onConnected()) 回 调 函 数 里 调 

用 getLastLocation()) 方 法 ， 这 个 回调 函数 在 client 准 备 好 的 时 候 被 调用 。 下 面 的 示例 代码 说 明 
了 请 求 和 一 个 对 响应 简单 的 处 理 : 


public class MainActivity extends ActionBarActivity implements 
ConnectionCallbacks, OnConnectionFailedListener ( 


@Override 
public void onConnected(Bundle connectionHint) { 
mLastLocation = LocationServices.FusedLocationApi.getLastLocation( 
mGoogleApiClient); 
if (mLastLocation != null) { 
mLatitudeText.setText(String.valueOf(mLastLocation.getLatitude())); 
mLongitudeText.setText(String.valueOf(mLastLocation.getLongitude())); 


getLastLocation()) 方 法 返回 一 个 Location 对 象 。 通 过 Location 对 象 ， 我 们 可 以 取得 地 理 位 置 的 
经 度 和 纬度 坐标 。 在 少数 情况 下 ， 当 位 置 不 可 用 时 ， 这 个 Location 对 象 会 返回 null 。 


下 一 课 ， 获 取 位 置 更 新 ， 教 你 如 何 周期 性 地 获取 位 置信 息 更 新 。 


获取 位 置 更 新 


编写 :penkzhou - /$ X :http://developer.android.com/training/location/receive-location- 
updates.html 


如 果 我 们 的 应 用 可 以 周期 性 地 跟踪 位 置 ， 那 么 应 用 可 以 给 用 户 提供 更 多 相关 信息 。 例 如 ， 如 
果 我 们 的 应 用 在 用 户 行走 或 者 驾车 时 帮助 找到 他 们 的 路 ， 或 者 如 果 我 们 的 应 用 跟踪 用 户 的 位 
置 ， 那 么 它 需 要 定期 获取 设备 的 位 置 。 除 了 地 理 位 置 之 外 (经度 和 纬度 ) ， 我 们 可 能 还 想 为 
用 户 提供 更 多 的 信息 ， 例 如 方位 (行驶 的 水 平方 向 ) 、 海 拔 或 者 设备 的 速度 。 这 些 信息 可 以 
在 Location 对 象 中 获得 ， 我 们 的 应 用 可 以 从 fused location provider 中 得 到 这 个 对 象 。 


当 我 们 用 getLastLocation()) 获取 设备 的 位 置 时 ， 如 上 一 节 课 获取 最 后 可 知 位 置 介 绍 的 一 样 ， 
一 个 更 加 直接 的 方法 是 从 fused location provider 中 请 求 周期 性 的 更 新 。 作 为 回应 ，API 根 据 
现 有 的 位 置 供应 源 ， 如 Wifi 和 GPS (Global Positioning System) ， 用 最 佳 位 置 周期 地 更 新 我 
们 的 应 用 。 这 些 providers、 我 们 请 求 的 权限 和 我 们 在 位 置 请 求 中 设置 的 选项 决定 了 位 置 的 精 
确 度 。 


这 节 课 介绍 如 何 用 fused location provider 的 requestLocationUpdates() 方 法 来 请 求 定 期 更 新 设 
备 的 位 置 。 


连接 Location Services 


应 用 的 Location Services 由 Google Play services 和 fused location provider 提供 。 为 了 用 
这 些 服务 ， 用 Google API Client 连接 到 我 们 的 应 用 ， 然 后 请 求 位 置 更 新 。 用 
GoogleApiClient 进行 连接 的 详细 步骤 请 见 获取 最 后 可 知 位 置 ， 包 括 了 请 求 当 前 位 置 。 


设备 的 最 后 可 知 位 置 提供 有 关 起 点 的 基准 信息 ， 在 开始 定期 更 新 位 置信 息 前 ， 保 证 应 用 拥有 
一 个 可 知 的 位 置 。 获 取 最 后 可 知 位 置 介 绍 了 如 何 通过 调用 getLastLocation()) 获取 最 后 可 知 位 
置 。 接 下 来 的 内 容 假设 我 们 的 应 用 已 经 取得 最 后 可 知 位 置 ， 并 已 将 最 后 可 知 位 置 作 为 一 个 
Location 对 象 保存 在 全 局 变量 mcurrentLocation 中 。 

使 用 位 置 服务 的 应 用 必须 请 求 位 置 权限 。 在 这 节 课 中 我 们 需要 很 好 的 定位 检测 ， 使 得 我 们 的 


应 用 可 以 从 可 用 的 位 置 供应 源 得 到 尽 可 能 精确 的 位 置 数据 。 在 我 们 应 用 的 manifest 文 件 中 ， 
用 uses-permission 节点 请 求 位 置 权 限 ， 如 下 所 示 : 


«manifest xmlns:android-"http://schemas.android.com/apk/res/android" 
package-"com.google.android.gms.location.sample.locationupdates" > 


«uses-permission android:name-"android.permission.ACCESS FINE LOCATION"/» 
«/manifest» 


设置 位 置 请 : 


创建 一 个 LocationRequest 以 保存 请 求 fused location provider 的 参数 。 参数 决定 了 请 求 
精确 度 的 水 平 。 对 于 位 置 请 求 中 所 有 可 用 的 选项 ， 请 见 dn 类 MAP: ° dX 
节 课 设置 更 新 闻 隔 、 最 快 更 新 闻 隔 和 优先 级 。 如 下 所 述 : 


更 新 闻 隔 


setInterval()) - 这 个 方法 设置 应 用 接收 位 置 更 新 的 速率 (每 毫秒 ) 。 注 意 如 果 另 一 个 应 用 正在 
接收 一 个 更 快 的 或 者 更 慢 的 更 新 速率 ， 又 或 者 根本 没有 更 新 〈 例 如 ， 设 备 还 没有 连接 ) » Ap 
么 我 们 应 用 的 位 置 更 新 速率 可 能 会 比 setInterval() 设置 的 速率 更 快 。 


最 快 更 新 闻 隔 


setFastestlnterval()) - 这 个 方法 设置 应 用 可 以 处 理 位 置 更 新 的 最 快速 率 (ARES) 。 因 为 其 它 
应 用 会 影响 到 已 发 送出 去 的 位 置 更 新 的 速率 ， 所 以 我 们 需要 设置 这 个 最 快速 率 。Google Play 
services location APIs 发 送 任何 应 用 用 setlnterval()) 请 求 的 最 快 的 更 新 速率 。 如 果 这 个 速率 
比 我 们 的 应 用 可 以 处 理 的 速率 还 要 快 ， 那 么 我 们 可 能 会 遇 到 UI 闪 烁 或 者 数据 溢出 等 问题 。 为 
了 避免 这 个 问题 ， 调 用 setFastestInterval()) 限制 更 新 速率 的 上 限 。 


优先 级 


setPriority()) - 这 个 方法 设置 请 求 的 优先 级 ， 为 Google Play services 位 置 服务 提供 了 关于 使 
用 哪个 位 置 源 的 强烈 的 上 暗示。 支持 下 面 几 个 值 : 


e PRIORITY BALANCED POWER ACCURACY - 这 个 设置 请 求 一 个 城市 街区 范围 的 位 
ies 度 (精确 度 约 为 100 米 ) 。 这 被 认为 是 一 个 粗略 的 精确 度 ， 也 可 能 是 耗 电 较 小 的 设 
。 对 于 这 个 设置 ， pesado EE 使 用 WiFi 和 基站 进行 定位 。 注 意 ， 无 论 如 何 ， 位 置 供 
E 择 依赖 于 很 多 其 它 的 因素 。 


e PRIORITY HIGH. ACCURACY - 这 个 设置 请 求 最 度 的 位 置信 息 。 对 于 这 个 设置 ， 位 
置 服务 更 可 能 使 用 GPS(Global Positioning m ee o 


e PRIORITY LOW POWER - | 包围 的 精确 度 (精确 度 约 为 10 公 
里 ) 。 这 被 认为 是 一 个 粗略 的 精确 度 ， 能 是 耗 电 较 小 的 设置 。 


e PRIORITY NO POWER - 如 果 需 要 对 功率 消耗 的 影响 微乎其微 ， 但 又 想 在 可 用 的 时 候 
接收 位 置 更 新 ， 那 么 使 用 这 个 设置 。 对 于 这 个 设置 ， 我 们 的 应 用 不 会 触发 任何 位 置 更 
新 ， 但 是 会 接收 由 其 它 应 用 触发 的 位 置 。 


下 面 的 示例 介绍 创建 位 置 请 求 和 设置 相关 的 参数 : 


protected void createLocationRequest() { 
LocationRequest mLocationRequest - new LocationRequest(); 
mLocationRequest.setInterval(10000); 
mLocationRequest.setFastestInterval(5000); 
mLocationRequest.setPriority(LocationRequest.PRIORITY HIGH ACCURACY); 


PRIORITY. HIGH. ACCURACY 的 优先 级 联合 在 我 们 应 用 的 manifest 文件 中 定义 的 
ACCESS FINE LOCATION 权限 和 一 个 5000 毫 秒 VB) 的 更 新 间隔 。 该 优先 级 使 fused 
location provider 返回 精确 到 几 英 尺 之 内 的 位 置 更 新 。 这 个 方法 适用 于 需要 实时 显示 位 置 的 地 
图 应 用 。 


能 提示 : 如 果 我 们 的 应 用 在 接收 一 个 位 置 更 新 后 接 入 网 络 或 者 执行 持续 时 间 长 的 工 
en 将 最 快 更 新 间隔 调整 到 一 个 更 慢 的 值 。 这 个 调整 防止 我 们 的 应 用 接收 不 可 用 的 
更 新 。 一 旦 持续 时 间 长 的 工作 完成 ， 将 最 快 更 新 闻 隔 改 回 一 个 快 的 值 。 


请 求 位 置 更 新 


我 们 已 经 设置 了 包含 应 用 位 置 更 新 要 求 的 位 置 请 求 ， 我 们 可 以 调用 requestLocationUpdates() 
来 启动 周期 性 的 更 新 。 在 Google API Client 提供 的 onConnected()) 回调 函数 ( 3$ client 准备 
好 之 后 会 调用 这 个 回调 函数 ) 中 启动 周期 性 更 新 。 


根据 请 求 的 形式 ，fused location provider 要 么 调用 LocationListener.onLocationChanged() 
回调 函数 并 传递 一 个 Location 对 象 ， 要 么 发 出 一 个 将 位 置信 息 包 含 在 扩展 数据 的 
Pendinglntent。 更 新 的 精确 度 和 频率 受 已 请 求 的 位 置 权限 和 在 位 置 请 求 对 象 中 设置 的 选 

因素 影 "o 


这 节 课 介绍 如 何 使 用 LocationListener 回调 函数 获取 位 置 更 新 。 调 用 
requestLocationUpdates() ,并 传 入 GoogleApiClient 的 实例 、LocationRequest 对 象 和 一 个 
LocationListener。 定 义 一 个 startLocationUpdates() 方法 ， 该 方法 在 onConnected()) 回调 
函数 被 调用 ， 如 下 面 的 示例 代码 所 示 : 


@Override 
public void onConnected(Bundle connectionHint) 1 


if (mRequestingLocationUpdates) 1 
startLocationUpdates(); 
} 
} 


protected void startLocationUpdates() { 
LocationServices.FusedLocationApi.requestLocationUpdates( 
mGoogleApiClient, mLocationRequest, this); 


注意 到 上 述 的 代码 片段 提 到 一 个 布尔 标志 位 ， mRequestingLocationUpdates ， 该 标志 位 用 于 判 
断 用 户 将 位 置 更 新 打开 还 是 关闭 。 关 于 这 个 标志 位 更 详细 的 介绍 ， 请 见 下 面 的 保存 Activity 的 
状态 的 内 容 。 


SAD ES a ELS] BH HK 


fused location provider 调用 LocationListener.onLocationChanged()) 回调 函数 。 这 个 回调 遂 
数 传 入 的 参数 是 一 个 含有 位 置 经 纬度 的 Location 对 象 。 下 面 的 代码 介绍 了 如 何 实现 
LocationListener 接口 和 定义 方法 ， 然 后 获取 位 置 更 新 的 时 间 惟 并 在 应 用 用 户 界面 上 显示 

Ro ARERR : 


public class MainActivity extends ActionBarActivity implements 
ConnectionCallbacks, OnConnectionFailedListener, LocationListener { 


QOverride 

public void onLocationChanged(Location location) { 
mCurrentLocation - location; 
mLastUpdateTime - DateFormat.getTimeInstance().format(new Date()); 
updateUI(); 

} 


private void updateUI() { 
mLatitudeTextView.setText(String.valueOf(mCurrentLocation.getLatitude())); 
mLongitudeTextView.setText(String.valueOf(mCurrentLocation.getLongitude())); 
mLastUpdateTimeTextView.setText(mLastUpdateTime); 


停止 位 置 更 新 


我 们 需要 考虑 当 activity 不 在 焦点 上 时 我 们 是 否 需 要 停止 位 置 更 新 ， euh 当 用 户 切换 到 另 一 
个 应 用 或 者 同一 个 应 用 的 不 同 ey 的 情况 。 假 如 应 用 即使 在 后 台 运 行 时 也 不 需要 收集 用 户 
数据 ， 将 会 有 利于 降低 功 耗 。 这 节 课 会 介绍 如 何在 activity 的 we 方法 里 停止 位 置 更 
新 。 


为 了 停止 位 置 更 新 ， 调 用 removeLocationUpdates()， 并 传 入 GoogleApiClient 对 象 的 实例 和 
一 个 LocationListener ， 如 下 面 的 示例 代码 所 示 : 


@Override 

protected void onPause() { 
super .onPause(); 
stopLocationUpdates(); 


protected void stopLocationUpdates() { 
LocationServices.FusedLocationApi.removeLocationUpdates( 
mGoogleApiClient, this); 


使 用 一 个 布尔 值 mRequestingLocationUpdates ， 来 判断 当前 位 置 更 新 是 否 打开 。 在 activity 
的 onResume()) 方法 里 ， 检 查 当 前 的 位 置 更 新 是 否 起 作用 。 如 果 位 置 更 新 不 起 作用 ， 那 么 激 


iu: 


@Override 
public void onResume() { 
super .onResume(); 
if (mGoogleApiClient.isConnected() && !mRequestingLocationUpdates) { 
startLocationUpdates(); 


保存 Activity 的 状态 


一 个 设备 配置 的 变动 ， 如 旋转 屏幕 或 者 改变 语言 ， 可 以 导致 当前 的 activity 崩溃 。 我 们 的 应 用 
必须 保存 任何 在 重新 创建 activity 时 需要 用 到 的 信息 。 一 种 方法 是 通过 一 个 保存 在 Bundle 对 
象 的 实例 状态 来 解决 这 个 问题 。 


下 面 的 示例 代码 介绍 了 如 何 用 activity 的 onSavelnstanceState()) 回调 函数 来 保存 实例 状态 : 


public void onSaveInstanceState(Bundle savedInstanceState) { 
savedInstanceState.putBoolean(REQUESTING LOCATION UPDATES KEY, 
mRequestingLocationUpdates); 
savedInstanceState.putParcelable(LOCATION KEY, mCurrentLocation); 
savedInstanceState.putString(LAST UPDATED TIME STRING KEY, mLastUpdateTime); 
super.onSaveInstanceState(savedInstanceState); 


定义 一 个 updatevaluesFromBundle() 方法 来 恢复 保存 在 activity 的 上 一 个 实例 的 值 (如 果 这 些 
值 可 用 的 话 ) 。 在 onCreate()) 中 调用 这 个 方法 。 如 下 所 示 : 


@Override 


public void onCreate(Bundle savedInstanceState) { 


updateValuesFromBundle(savedInstanceState); 


private void updateValuesFromBundle(Bundle savedInstanceState) { 
if (savedInstanceState !- null) { 


// Update the value of mRequestingLocationUpdates from the Bundle, and 
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} 


make sure that the Start Updates and Stop Updates buttons are 
correctly enabled or disabled. 
(savedInstanceState.keySet().contains(REQUESTING LOCATION UPDATES KEY)) { 
mRequestingLocationUpdates - savedInstanceState.getBoolean( 
REQUESTING LOCATION UPDATES KEY); 
setButtonsEnabledState(); 


Update the value of mCurrentLocation from the Bundle and update the 
UI to show the correct latitude and longitude. 
(savedInstanceState.keySet().contains(LOCATION KEY)) { 

// Since LOCATION KEY was found in the Bundle, we can be sure that 
// mCurrentLocationis not null. 

mCurrentLocation - savedInstanceState.getParcelable(LOCATION KEY); 


Update the value of mLastUpdateTime from the Bundle and update the UI. 
(savedInstanceState.keySet().contains(LAST UPDATED TIME STRING KEY)) { 
mLastUpdateTime - savedInstanceState.getString( 

LAST UPDATED TIME STRING KEY); 


updateUI(); 


更 多 关于 保存 实例 状态 的 内 容 ， 请 看 Android Activity 类 的 参考 文档 。 


Note : 为 了 可 以 更 加 持久 地 存储 ， 我 们 可 以 将 用 户 的 偏好 设 定 保存 在 应 用 的 
SharedPreferences 中 。 在 activity 的 onPause()) 方法 中 设置 偏好 设 定 ， 在 
onResume()) 中 获取 这 些 设 定 。 更 多 关于 偏好 设 定 的 内 容 ， 请 见 保存 到 Rreference 。 


下 一 节 课 ， 显 示 位 置地 址 ， 介 绍 如 何 显示 指定 位 置 的 街道 地 址 。 


显示 位 置地 址 


编写 :penkzhou - 原文 :http://developer.android.com/training/location/display- 
address.html 


获取 最 后 可 知 位 置 和 获取 位 置 更 新 课程 描述 了 如 何以 一 个 Location 对 象 的 形式 获取 用 户 的 位 置 
信息 ， 这 个 位 置信 息 包 括 了 经 纬度 。 尽 管 经 纬度 对 计算 地 理 距 离 和 在 地 图 上 显示 位 置 很 有 

用 ， 但 是 更 多 情况 下 位 置 的 地 址 更 有 有 用。 例如， 如 果 我 们 想 让 用 户 知 道 他 们 在 哪里 ， 那 么 一 
个 街道 地 址 比 地 理 坐 标 ( 经度/ 纬度 ) 更 加 有 意义 。 


使 用 Android 框架 位 置 APls 的 Geocoder 类 ， 我 们 可 以 将 地 址 转换 成 相应 的 地 理 坐 标 。 这 个 
过 程 叫做 地 理 编码 。 或 者 ， 我 们 可 以 将 地 理 位 置 转 换 成 相应 的 地 址 。 这 种 地 址 查找 功能 叫做 
反 向 地 理 编码 。 


这 节 课 介绍 了 如 何 用 getFromLocation() 方法 将 地 理 位 置 转换 成 地 址 。 这 个 方法 返回 与 制定 经 
纬度 相对 应 的 估计 的 街道 地 址 。 


at s. 
获取 地 理 位 置 

设备 的 最 后 可 知 位 置 对 于 地 址 查找 功能 是 很 有 用 的 基础 。 获 取 最 后 可 知 位 置 介 绍 了 如 何 通过 
调用 fused location provider 提供 的 getLastLocation()) 方法 找到 设备 的 最 后 可 知 位 置 。 


为 了 访问 fused location provider， 我 们 需要 创建 一 个 Google Play services API client 的 实 
例 。 关 于 如 何 连 接 client， 请 见 连 接 Google Play Services 。 


为 了 让 fused location provider 得 到 一 个 准确 的 街道 地 址 ， 在 应 用 的 manifest 文件 添加 位 置 


权限 ACCESS FINE LOCATION ， 如 下 所 示 : 


«manifest xmlns:android-"http://schemas.android.com/apk/res/android" 
package="com.google.android.gms.location.sample.locationupdates" > 


<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> 


</manifest> 


定义 一 个 Intent 服务 来 取得 地 址 


Geocoder 类 的 getFromLocation() 方法 接收 一 个 经 度 和 纬度 ， 返 回 一 个 地 址 列表 。 这 个 方法 
是 同步 的 ， 可 能 会 花 很 长 时 间 来 完成 它 的 工作 ， 所 以 我 们 不 应 该 在 应 用 的 主线 程 和 UI 线程 里 
调用 这 个 方法 。 


IntentService 类 提供 了 一 种 结构 使 一 个 任务 在 后 台 线 程 运行 。 使 用 这 个 类 ， 我 们 可 以 在 不 影 
* UI 响应 速度 的 情况 下 处 理 一 个 长 时 间 运 行 的 操作 。 注 意 到 ，AsyncTask 类 也 可 以 执行 后 台 
操作 ， 但 是 它 被 设计 用 于 短 时 间 运 行 的 操作 。 在 activity 重新 创建 时 (例如 当 设 备 旋转 

时 ) ，AsyncTask 不 应 该 保存 UI 的 引用 。 相 反 ， 当 activity 重建 时 ， 不 需要 取消 
IntentService ° 


定义 一 个 继承 IntentService 的 类 rFetchAddressIntentservice 。 这 个 类 是 地 址 查找 服务 。 这 个 
Intent 服务 在 一 个 工作 线程 上 异步 地 处 理 一 个 intent， 并 在 它 离开 这 个 工作 时 自动 停止 。 
Intent 外 加 的 数据 提供 了 服务 需要 的 数据 ， 包 括 一 个 用 于 转换 成 地 址 的 Location 对 但 和 一 个 
用 于 处 理 地 址 查找 结果 的 ResultReceiver 对 象 。 这 个 服务 用 一 个 Geocoder 来 获取 位 置 的 地 
址 ， 并 且 将 结果 发 送 给 ResultReceiver 。 


在 应 用 的 manifest 文件 中 定义 Intent 服务 
在 manifest 文件 中 添加 一 个 节点 以 定义 intent 服务 : 


«manifest xmlns:android-"http://schemas.android.com/apk/res/android" 
package="com.google.android.gms.location.sample.locationaddress" > 
<application 


<service 
android:namez".FetchAddressIntentService" 
android:exported-"false"/» 
«/application» 


«/manifest» 


Note : manifest 文件 里 的 zservice» Y & € X 6,2 —^- intent filter， 这 是 因为 我 们 的 
i. activity 通过 指定 intent 用 到 的 类 的 名 字 来 创建 一 个 隐 式 的 intent © 


创建 一 个 Geocoder 


将 一 个 地 理 位 置 传 换 成 地 址 的 过 程 叫 做 反 向 地 理 编 码 id 通过 实现 FetchAddressIntentService 
类 的 onHandlelntent()) 来 执行 intent 服务 的 主要 工作 ， 即 反 向 地 理 编码 请 求 。 创 建 一 个 
Geocoder 对 象 来 处 理 反 向 地 理 编 码 。 


一 个 区 域 设置 代表 一 个 特定 的 地 理 上 的 或 者 语言 上 的 区 域 。Locale 对 象 用 于 调整 信息 的 呈现 
方式 ， 例 如 数字 或 者 日 期 ， 来 适应 区 域 设 置 表示 的 区 域 的 约定 。 传 一 个 Locale 对 象 到 
Geocoder 对 象 ， 确 保 地 址 结果 为 用 户 的 地 理 区 域 作 出 了 本 地 化 。 


@Override 
protected void onHandleIntent(Intent intent) { 
Geocoder geocoder = new Geocoder(this, Locale.getDefault()); 


获取 街道 地 址 数据 


下 一 步 是 从 geocoder 获取 街道 地 址 ， 处 理 可 能 出 现 的 错误 ， 和 将 结果 返回 给 请 求 地址 的 
activity。 我 们 需要 两 个 分 别 代 表 成 功 和 失败 的 数字 常 a en 。 定 义 一 
个 constants 类 来 包含 这 些 值 ， 如 下 所 示 : 


public final class Constants { 

public static final int SUCCESS RESULT - 0; 

public static final int FAILURE RESULT - 1; 

public static final String PACKAGE NAME = 
"com.google.android.gms.location.sample.locationaddress"; 

public static final String RECEIVER = PACKAGE NAME + ".RECEIVER"; 

public static final String RESULT DATA KEY = PACKAGE NAME + 
".RESULT DATA KEY"; 

public static final String LOCATION DATA EXTRA = PACKAGE NAME + 
".LOCATION DATA EXTRA"; 


为 了 RUE 对 应 的 街道 地 址 ， 调 用 getFromLocation()， 传 入 位 置 对 象 的 经 度 和 纬 
度 ， 以 及 我 们 想 要 返回 的 地 址 的 最 大 数量 。 在 这 种 情况 下 ， 我 们 只 需要 一 个 地 址 。geocoder 
返回 一 个 地 址 数组 。 如 果 没 有 找到 定位 置 的 地 址 ， 那 么 它 会 返回 空 的 列表 。 如 果 没 有 
可 用 的 后 台地 理 编 码 服 务 ，geocoder 会 返回 null。 


p 


如 下 面 代码 介绍 来 检查 下 述 这些 错 误 。 如 果 出 现 错误 ， 就 将 相应 的 错误 信息 传 给 变量 
errorMessage ， 从 而 将 错误 信息 发 送 给 发 出 请 求 的 activity : 


e No location data provided - Intent 的 附加 数据 没有 包含 反 向 地 理 编码 需要 用 到 的 
Location 对 象 。 

e Invalid latitude or longitude used - Location 对 象 提 供 的 纬度 和 /或 者 经 度 无 效 。 

e No geocoder available - 由 于 网 络 错误 或 者 IO ， 导 致 后 台地 理 编 码 服务 不 可 用 。 

e Sorry, no address found - geocoder 找 不 到 指定 纬度 /经 度 对 应 的 地 址 。 


使 用 Address 类 中 的 getAddressLine()) 方法 来 获得 地 址 对 象 的 个 别 行 后 将 这 些 行 加 入 一 
个 地 址 fragment 列表 当中 。 其 中 ， 这 个 地 址 fragment 列表 准备 好 返 回 到 * 出 地 址 请 求 的 
activity。 

为 了 将 结果 返回 给 发 出 地 址 请 求 的 activity， 需 要 调用 deliverResultToReceiver() 方法 (X 


Medo cR Mei BiH Rim) 。 nea | 的 成 功 /失败 数字 代码 和 一 个 字符 囊 组 
成 。 在 反 向 地 理 编码 成 功 的 情况 下 ， 这 个 字符 串 包 含 着 地 址 。 在 失败 的 情况 下 ， 这 个 字符 囊 


包含 错误 的 信息 。 如 下 所 示 : 


@Override 
protected void onHandleIntent(Intent intent) { 
String errorMessage = ""; 


// Get the location passed to this service through an extra. 
Location location = intent.getParcelableExtra( 
Constants.LOCATION DATA EXTRA); 


List«Address» addresses - null; 


try { 
addresses - geocoder.getFromLocation( 
location.getLatitude(), 
location.getLongitude(), 
// In this sample, get just a single address. 
1); 
} catch (IOException ioException) { 
// Catch network or other I/O problems. 
errorMessage = getString(R.string.service not available); 
Log.e(TAG, errorMessage, ioException); 
) catch (IllegalArgumentException illegalArgumentException) 1 
// Catch invalid latitude or longitude values. 
errorMessage - getString(R.string.invalid lat long used); 


Log.e(TAG, errorMessage + ". " + 
"Latitude = " + location.getLatitude() + 
", Longitude = " + 


location.getLongitude(), illegalArgumentException) ; 


// Handle case where no address was found. 
if (addresses == null || addresses.size() == 0) { 
if (errorMessage.isEmpty()) { 
errorMessage = getString(R.string.no address found); 
Log.e(TAG, errorMessage); 
} 
deliverResultToReceiver(Constants.FAILURE RESULT, errorMessage); 
} else { 
Address address = addresses.get(9); 
ArrayList<String> addressFragments = new ArrayList<String>(); 


// Fetch the address lines using getAddressLine, 

// join them, and send them to the thread. 

for(int i = 0; i < address.getMaxAddressLineIndex(); i++) { 

addressFragments.add(address.getAddressLine(i)); 

} 

Log.i(TAG, getString(R.string.address found)); 

deliverResultToReceiver(Constants.SUCCESS RESULT, 
TextUtils.join(System.getProperty("line.separator"), 


addressFragments)); 


把 地 址 返回 给 请 求 端 


Intent 服务 最 后 要 做 的 事情 是 将 地 址 返回 给 启动 服务 的 activity 里 的 ResultReceiver。 这 个 
ResultReceiver 类 允许 我 们 发 送 一 个 带 有 结果 的 数字 代码 和 一 个 包含 结果 数据 的 ii 。 这 个 
数字 代码 说 明了 地 理 编 码 请 求 是 成 功 还 是 失败 。 在 反 向 地 理 编 码 成 功 的 情况 下 ， 这 个 消息 
含 着 地 址 。 在 失败 的 情况 下 ， 这 个 消息 包含 一 些 描 述 失败 原因 的 文本 。 


我 们 已 经 可 以 从 geocoder 取得 地 址 ， 捕 获 到 可 能 出 现 的 错误 ， 调 用 
deliverResultToReceiver() 方法 。 现 在 我 们 需要 定义 deliverResultToReceiver() 方法 来 将 
结果 代码 和 消息 包 发 送 给 结果 接收 端 。 


对 于 结果 代码 ， 使 用 已 经 传 给 deliverResultToReceiver() 方法 的 resultcode 参数 的 值 。 对 
于 消息 包 的 结构 ， 连 接 constants 类 的 RESULT_DATA KEY 常量 (定义 与 获取 街道 地 址 数据 ) 
和 传 给 deliverResultToReceiver() 方法 的 message 参数 的 值 。 如 下 所 示 : 


public class FetchAddressIntentService extends IntentService { 
protected ResultReceiver mReceiver; 


private void deliverResultToReceiver(int resultCode, String message) { 
Bundle bundle - new Bundle(); 
bundle.putString(Constants.RESULT DATA KEY, message); 
mReceiver.send(resultCode, bundle); 


启动 Intent 服务 


上 节 课 定义 的 intent 服务 在 后 tenia 责 提取 与 指定 地 理 位 置 相对 应 的 地 
址 。 当 我 们 启动 服务 ，Android 框架 会 实例 化 并 局 ba (如 果 该 服务 没有 运行 ) ， 并 且 如 果 
需要 的 话 ， 创 建 一 个 进程 。 is se > 那么 让 它 保持 运行 状态 。 因 为 服务 继承 于 
IntentService， 所 以 当 所 有 intent 都 被 处 理 完 之 后 ， 该 服务 会 自动 停止 。 


在 我 们 应 用 的 主 activity 中 启动 服务 ， 并 且 创 建 一 个 Intent 来 把 数据 传 给 服务 。 我 们 需要 创建 
一 个 显 式 的 intent， 这 是 因为 我 们 只 想 我 们 的 服务 响应 该 intent。 详 细 请 见 Intent Types ° 


为 了 创建 一 个 显 式 的 intent， 需 要 为 服务 指定 要 用 到 的 类 
名 : FetchAddressIntentService.class 。 在 intent 附加 数据 中 传 入 两 个 信息 : 


e 一 个 用 于 处 理 地 址 查找 结果 的 ResultReceiver 。 
e 一 个 包含 想 要 转换 成 地 址 的 纬度 和 经 度 的 Location 对 象 。 


下 面 的 代码 介绍 了 如 何 启动 intent 服务 : 


public 


class MainActivity extends ActionBarActivity implements 
ConnectionCallbacks, OnConnectionFailedListener { 


protected Location mLastLocation; 


private AddressResultReceiver mResultReceiver; 


protected void startIntentService() { 


Intent intent - new Intent(this, FetchAddressIntentService.class); 
intent.putExtra(Constants.RECEIVER, mResultReceiver); 
intent.putExtra(Constants.LOCATION DATA EXTRA, mLastLocation); 
startService(intent); 


当 用 户 请 求 查 找 地 理 地 址 时 ， 调 用 上 述 的 startintentservice() 方法 。 例 如 ， 用 户 可 能 会 在 
我 们 应 用 的 UI 上 面 点 击 提取 地 址 按钮 。 在 启动 intent 服务 之 前 ， 我 们 需要 检查 是 否 已 经 连接 
到 Google Play services。 下 面 的 代码 片段 介绍 在 一 个 按钮 handler 中 调用 


startIntentService() 方法 。 


public 
// 
"74 
uf 


void fetchAddressButtonHandler(View view) { 

Only start the service to fetch the address if GoogleApiClient is 
connected. 

(mGoogleApiClient.isConnected() && mLastLocation !- null) ( 


startIntentService(); 


If GoogleApiClient isn't connected, process the user's request by 
setting mAddressRequested to true. Later, when GoogleApiClient connects, 
launch the service to fetch the address. As far as the user is 
concerned, pressing the Fetch Address button 

immediately kicks off the process of getting the address. 


mAddressRequested - true; 
updateUIWidgets(); 


如 果 用 户 点 击 了 应 用 U 上 面 的 提取 地 址 按钮 ， 那 么 我 们 必须 在 Google Play services 连接 稳 
定之 后 启动 intent 服务 。 下 面 的 代码 片段 介绍 了 调用 Google API Client 提供 的 
onConnected()) 回调 函数 中 的 startIntentService() 方法 。 


public class MainActivity extends ActionBarActivity implements 
ConnectionCallbacks, OnConnectionFailedListener ( 


@Override 
public void onConnected(Bundle connectionHint) { 
// Gets the best and most recent location currently available, 
// which may be null in rare cases when a location is not available. 
mLastLocation = LocationServices.FusedLocationApi.getLastLocation( 
mGoogleApiClient); 


if (mLastLocation !- null) { 
// Determine whether a Geocoder is available. 
if (!Geocoder.isPresent()) { 
Toast.makeText(this, R.string.no_geocoder_available, 
Toast .LENGTH_LONG) .show(); 
return; 


if (mAddressRequested) { 
startIntentService(); 


获取 地 理 编 码 结 


Intent 服务 已 经 处 理 完 地 理 编 码 请 求 ， 并 用 ResultReceiver 将 结果 返回 给 发 出 请 求 的 
activity。 在 发 出 请 求 的 activity 里 ， 定 义 一 个 继承 于 ResultReceiver 的 


AddressResultReceiver ? 用 于 处 理 在 FetchAddressIntentService 中 的 响应 7 


结果 包含 一 个 数字 代码 ( resultcode ) 和 一 个 包含 结果 数据 ( resultpata) 的 消息 。 如 果 反 
向 地 理 编 码 成 功 的 话 ， resultData 会 包含 地 址 。 如 果 失 败 ， resultpata 包含 描述 失败 原 
的 文本 。 关 于 错误 信息 更 详细 的 内 容 ， 请 见 把 地 址 返回 给 请 求 端 


重 写 onReceiveResult() 方法 来 处 理发 送 给 接收 端的 结果 ， 如 下 所 示 : 


public class MainActivity extends ActionBarActivity implements 
ConnectionCallbacks, OnConnectionFailedListener ( 


class AddressResultReceiver extends ResultReceiver { 
public AddressResultReceiver(Handler handler) { 
super(handler); 


@Override 
protected void onReceiveResult(int resultCode, Bundle resultData) { 


// Display the address string 

// or an error message sent from the intent service. 
mAddressOutput = resultData.getString(Constants.RESULT DATA KEY); 
displayAddressOutput(); 


// Show a toast message if an address was found. 
if (resultCode == Constants.SUCCESS_RESULT) { 
showToast(getString(R.string.address found)); 


482 


创建 和 监视 地 理 围 栏 


编写 :penkzhou - 原文 :http://developer.android.com/training/location/geofencing.html 


地 理 围 栏 将 用 户 no dil 附件 地 点 特征 感知 相 结合 。 为 了 标示 一 个 感 兴趣 的 位 置 ， 我 
们 需要 指定 这 个 位 置 的 经 纬度 。 为 了 调整 位 置 的 邻近 度 ， 需 要 添加 一 个 半径 。 经 纬度 和 半径 
D v ， 即 在 感 兴趣 的 位 置 创建 一 个 圆 形 区 域 或 者 围栏 


我 们 可 以 有 多 个 活动 的 地 理 围栏 (限制 是 一 个 设备 用 户 100 个 ) 。 对 于 每 个 地 理 围 栏 ， 我 们 可 
以 让 Location Services 发 出 进入 和 离开 事件 ， 或 者 我 们 可 以 在 触发 一 个 事件 之 前 ， 指 定 在 某 
个 地 理 围栏 区 域 等 待 一 段 时 间或 者 停留 。 通 过 指定 一 个 以 毫秒 为 单位 的 截止 时 间 ， 我 们 可 以 
限制 任何 一 个 地 理 围栏 的 持续 时 间 。 当 地 理 围 栏 失 效 后 ，Location Services 会 自动 删除 这 个 
地 理 围栏 。 
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这 节 课 介绍 如 何 添加 和 删除 地 理 围栏 ， 和 用 IntentService 监听 地 理 位 置 变化 。 


HB ALEX 


请 求 地 理 围栏 监视 的 第 一 步 就 是 设置 必要 的 权限 。 在 使 用 地 理 围栏 时 ， 我 们 必须 设置 
ACCESS FINE LOCATION 权限 。 在 应 用 的 manifest 文件 中 添加 如 下 子 节点 即 可 : 


«uses-permission android:name-"android.permission.ACCESS FINE LOCATION"/» 


如 果 想 要 用 IntentService 监听 地 理 位 置 变化 ， 那 么 还 需要 添加 一 个 节点 来 指定 服务 名 字 。 这 
个 节点 必须 是 的 子 节点 : 


«application 
android:allowBackup="true"> 


«service android:name=".GeofenceTransitionsIntentService"/> 
<application/> 


为 了 访问 位 置 API， 我 们 需要 创建 一 个 Google Play services API client 的 实例 。 想 要 学 习 如 
何 连 接 client， 请 见 连接 Google Play Services。 


创建 和 添加 地 理 围 栏 


我 们 的 应 用 需要 用 位 置 API 的 builder 类 来 创建 地 理 围栏 ， 用 convenience 类 来 添加 地 理 围 
兰 。 另 外 ， 我 们 可 以 定义 一 个 Pendinglntent (将 在 这 节 课 介绍 ) 来 处 理 当 地 理 位 置 发 生 迁 移 
It > Location Services 发 出 的 intent ° 


创建 地 理 围栏 对 象 


首先 ， 用 Geofence.Builder 创建 一 个 地 理 围 栏 ， 设 置 想 要 的 半径 ， 持 续 时 间 ， 和 地 理 围 栏 迁 
移 的 类 型 。 例 如 ， 填 充 一 个 叫做 mGeofencetist 的 list 对 象 : 


mGeofenceList.add(new Geofence.Builder() 
// Set the request ID of the geofence. This is a string to identify this 
// geofence. 
.setRequestId(entry.getKey()) 


.setCircularRegion( 
entry.getValue().latitude, 
entry.getValue().longitude, 
Constants.GEOFENCE RADIUS IN METERS 
) 
.setExpirationDuration(Constants.GEOFENCE EXPIRATION IN MILLISECONDS) 
.setTransitionTypes(Geofence.GEOFENCE TRANSITION ENTER | 
Geofence.GEOFENCE TRANSITION EXIT) 
.build()); 


这 个 例子 从 一 个 固定 的 文件 中 获取 数据 。 在 实际 情况 下 ， 应 用 可 能 会 根据 用 户 的 位 置 动态 地 
创建 地 理 围 栏 。 


a 


+s 


指定 地 理 围栏 和 初始 化 触发 中 


8 


下 面 的 代码 用 到 GeofencingRequest X » RRR T GeofencingRequestBuilder 类 来 需要 监 
视 的 地 理 围 栏 和 设置 如 何 触 发 地 理 围栏 事件 : 


private GeofencingRequest getGeofencingRequest() { 
GeofencingRequest.Builder builder - new GeofencingRequest.Builder(); 
builder.setInitialTrigger(GeofencingRequest.INITIAL TRIGGER ENTER); 
builder.addGeofences(mGeofenceList); 
return builder.build(); 


这 个 例子 介绍 了 两 个 地 理 围 栏 触发 器 。 当 设备 进入 一 个 地 理 围栏 时 ， 

GEOFENCE TRANSITION ENTER 转移 会 触发 。 当 设备 离开 一 个 地 理 围栏 时 ， 
GEOFENCE TRANSITION EXIT 转移 会 触发 。 如 果 设 备 已 经 在 地 理 围栏 里 面 ， 那 么 指定 
INITIAL. TRIGGER ENTER 来 通知 位 置 服务 触发 GEOFENCE_ TRANSITION ENTER ° 


在 很 多 情况 下 ， 使 用 INITIAL _TRIGGER _DWELL 可 能 会 更 好 。 仅 仅 当 由 于 到 达 地 理 围 栏 中 
已 定义 好 的 持续 时 间 ， 而 导致 用 户 停 止 时 ，INITIAL_TRIGGER_DWELL 才 会 触发 事件 。 这 个 
方法 可 以 减少 当 设 备 短暂 地 进入 和 离开 地 理 围 栏 时 ， 由 大 量 的 通知 造成 的 “垃圾 警告 信息 ”。 另 
一 种 获取 最 好 的 地 理 围栏 结果 的 策略 是 设置 最 小 半径 为 100 米 。 这 有 助 于 估计 典型 的 Wifi 网 络 
的 位 置 精确 度 ， 也 有 利于 降低 设备 的 功 耗 。 


为 地 理 围 栏 转移 定义 Intent 


从 Location Services 发 送 来 的 Intent 能 够 触发 各 种 应 用 内 的 动作 ， 但 是 不 能 用 它 来 打开 一 个 
Activity 或 者 Fragment， 这 是 因为 应 用 内 的 组 件 只 能 在 响应 用 户 动作 时 才 可 见 。 大 多 数 情 况 
下 ， 处 理 这 一 类 Intent 最 好 使 用 IntentService。 一 个 IntentService 可 以 推送 一 个 通知 ， 可 以 
进行 长 时 间 的 后 台 作 业 ， 可 以 将 intent 发 送 给 其 他 的 services ， 还 可 以 发 送 一 个 广播 
intent。 下 面 的 代码 展示 了 如 何 定义 一 个 Pendinglntent 来 启动 一 个 IntentService: 


public class MainActivity extends FragmentActivity { 


private PendingIntent getGeofencePendingIntent() { 
// Reuse the PendingIntent if we already have it. 
if (mGeofencePendingIntent != null) { 
return mGeofencePendingIntent; 


} 


Intent intent = new Intent(this, GeofenceTransitionsIntentService.class); 
// We use FLAG_UPDATE_CURRENT so that we get the same pending intent back when 
// calling addGeofences() and removeGeofences(). 
return PendingIntent.getService(this, ©, intent, PendingIntent. 
FLAG UPDATE CURRENT); 


添加 地 理 围栏 


使 用 GeoencingApi.addGeofences() 方法 来 添加 地 理 围栏 。 为 该 方法 提供 Google API 
client > GeofencingRequest 对 象 和 Pendinglntent。 下 面 的 代码 ， 在 onResult()) 中 处 理 结 
果 ， 假 设 主 activity 实现 ResultCallback ° 


public class MainActivity extends FragmentActivity { 


LocationServices.GeofencingApi.addGeofences( 
mGoogleApiClient, 
getGeofencingRequest(), 
getGeofencePendingIntent() 

).setResultCallback(this); 


处 理 地 理 围栏 转移 


当 Location Services 探测 到 用 户 进入 或 者 离开 一 个 地 理 围栏 ， 它 会 发 送 一 个 包含 在 
Pendinglntent 的 Intent， 这 个 Pendinglntent 就 是 在 添加 地 理 围栏 时 被 我 们 包括 在 请 求 当 

中 。 这 个 Intent 被 一 个 类 似 GeofenceTransitionsIntentService 的 service 接收 ， 这 个 
service 从 intent 得 到 地 理 围栏 事件 ， 决 定 地 理 围栏 转移 的 类 型 ， 和 决定 触发 哪个 已 定义 的 地 
理 围 栏 。 然 后 它 会 发 出 一 个 通知 。 


下 面 的 代码 介绍 了 如 何 定义 一 个 IntentService。 这 个 IntentService 在 地 理 围 栏 转移 出 现时 ， 
会 推送 一 个 通知 。 当 用 户 点 击 这 个 通知 ， 那 么 应 用 的 主 activity 会 出 现 : 


public class GeofenceTransitionsIntentService extends IntentService { 


protected void onHandleIntent(Intent intent) ( 
GeofencingEvent geofencingEvent - GeofencingEvent.fromIntent(intent); 
if (geofencingEvent.hasError()) { 
String errorMessage - GeofenceErrorMessages.getErrorString(this, 
geofencingEvent.getErrorCode()); 
Log.e(TAG, errorMessage); 
return; 


// Get the transition type. 


int geofenceTransition = geofencingEvent.getGeofenceTransition(); 


// Test that the reported transition was of interest. 
if (geofenceTransition -- Geofence.GEOFENCE TRANSITION ENTER || 
geofenceTransition == Geofence.GEOFENCE TRANSITION EXIT) { 


// Get the geofences that were triggered. A single event can trigger 
// multiple geofences. 


List triggeringGeofences - geofencingEvent.getTriggeringGeofences(); 


// Get the transition details as a String. 

String geofenceTransitionDetails - getGeofenceTransitionDetails( 
this, 
geofenceTransition, 
triggeringGeofences 


); 


// Send notification and log the transition details. 
sendNotification(geofenceTransitionDetails) ; 
Log.i(TAG, geofenceTransitionDetails); 
} else { 
// Log the error. 
Log.e(TAG, getString(R.string.geofence_transition_invalid_type, 
geofenceTransition) ); 


在 通过 PendingIntent 检测 转移 事件 之 后 ， 这 个 IntentService 获取 地 理 围 栏 转移 类 型 和 测试 
一 个 事件 是 不 是 应 用 用 来 触发 通知 的 一 要么 = vere TRANSITION ENTER : € 
4x GEOFENCE _ TRANSITION_EXIT。 然 后 ， 这 个 service 会 发 出 一 个 通知 并 且 记 录 转 移 
的 详细 信息 。 


停止 地 理 围栏 监视 


当 不 再 需要 监视 地 理 围 栏 或 者 想 要 节省 设备 的 电池 电量 和 CPU 周期 时 ， 需 要 停止 地 理 围栏 监 
视 。 我 们 可 以 在 用 于 添加 和 删除 地 理 围栏 的 主 activity 里 停止 地 理 围 栏 监视 ; 删除 地 理 围栏 会 
导致 它 马 上 停止 。API 要 么 通过 request IDs， 要 么 通过 删除 与 指定 Pendinglntent 相关 的 地 
理 围 栏 来 删除 地 理 围栏 。 


下 面 的 代码 通过 Pendinglntent 删除 地 理 围 栏 ， 当 设备 进入 或 者 离开 之 前 已 经 添加 的 地 理 围栏 
时 ， 停止 所 有 通知 : 


LocationServices.GeofencingApi.removeGeofences( 
mGoogleApiClient, 
// This is the same pending intent that was used in addGeofences(). 
getGeofencePendingIntent() 
).setResultCallback(this); // Result processed in onResult(). 


你 可 以 将 地 理 围栏 同 其 他 位 置 感知 的 特性 结合 起 来 ， 比 如 周期 性 的 位 置 更 新 。 像 要 了 解 更 多 
的 信息 ， 请 看 本 章 的 其 它 课程 。 


Android 可 穿戴 应 用 


编写 :kesenhoo - 原文 : http;//developer.android.com/training/building-wearables.html 


这 些 课程 将 教 我 们 如 何在 手持 应 用 上 构建 notification， 并 且 使 得 这 些 notification 能 够 自动 同步 
到 可 穿戴 设备 上 。 同 样 也 会 教 我 们 如 何 创 建 直接 运行 在 可 穿戴 设备 上 的 应 用 。 


Note : 关于 这 几 节 课 用 到 的 API 的 详细 信息 ， 请 见 Wear API reference documentation ° 
w T Notification T È 2 49 44t 


学 习 如 何 构建 运行 在 手持 设备 的 上 得 notification 并 且 使 得 他 们 能 够 同步 到 可 穿戴 上 设备 时 有 良 
好 的 体验 。 


创建 可 穿戴 应 用 

学 习 如 何 构建 直接 运行 在 可 穿戴 设备 上 的 应 用 。 
创建 自 定 义 的 UI 

学 习 如 何 为 可 穿戴 应 用 创建 自 定 义 的 界面 。 
发 送 与 同步 数据 

学 习 如 何在 手持 设备 与 可 穿戴 设备 之 间 同 步 数 据 。 
创建 表盘 

学 习 如 何 创 建 表盘 。 

令 测 位 置 


学 习 如 何在 Android 穿 戴 设 备 上 检测 位 置 数据 。 


A Notification A 2» T F RAF 


编写 :Wangyachen - 原文 : 
http://developer.android.com/training/wearables/notifications/index.html 
当 一 部 Android 手 持 设备 (手机 或 平板 ) 与 Android 可 穿戴 设备 连接 后 ， 手 持 设 备 能 够 自动 与 可 
穿戴 设备 共享 Notification。 在 可 穿戴 设备 上 ， 每 个 Notification 都 是 以 一 张 新 卡 片 的 形式 出 现 
在 context stream 中 。 
与 此 同时 ， 为 了 给 予 用 户 以 最 佳 的 体验 ， 开 发 者 应 当 为 自己 创建 的 Notification 增 加 一 些 具备 
可 穿戴 特性 的 功能 。 下 面 的 课程 将 指导 我 们 如 何 实 现 同 时 支持 手持 设备 和 可 穿戴 设备 的 
Notification ° 
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Figure 1. 同时 展示 在 手持 设备 和 可 穿戴 设备 的 Notification 


Lessons 


创建 Notification 
学 习 如 何 应 用 Android support library 创 建 具 备 可 穿戴 特性 的 Notification ° 
在 Notification 中 接收 语音 输入 


学 习 在 可 穿戴 式 设备 上 的 Notification 添 加 一 个 action 以 接收 来 自用 户 的 语音 输入 ， 并 且 将 录入 
的 消息 传递 给 手持 设备 应 用 。 


为 Notification 添 加 页 面 
学 习 如 何 为 Notification 创 建 附 加 的 页 面 ， 使 得 用 户 在 向 左 滑动 时 能 看 到 更 多 的 信息 。 


将 Notification 放 成 一 受 


学 习 如 何 将 我 们 应 用 中 所 有 相似 的 notification 放 在 一 个 堆 受 中 ， 使 得 在 不 将 多 个 卡片 添加 到 卡 
片 流 的 情况 下 ， 人 允许 用 户 能 够 独立 地 查看 每 一 个 Notification 。 


为 可 穿戴 设备 创建 Notification 


编写 :wangyachen - R x : 


http://developer.android.com/training/wearables/notifications/creating.html 


使 用 NotificationCompat.Builder 来 创建 可 以 发 送 给 可 穿戴 设备 的 手持 设备 Notification。 当 我 
们 使 用 这 个 类 创建 Notification 之 后 ， 无 论 Notification 出 现在 手持 式 设备 上 还 是 可 穿戴 设备 上 ， 
系统 都 会 把 Notification 正 确 地 显示 出 来 。 


Note : 使 用 RemoteViews a ZR I ÉL ELS layout， 并 且 可 穿戴 设备 上 只 显 
示 文 本 和 图 标 。 但 是 ， 通 过 创建 一 个 运行 在 可 穿戴 设备 上 的 应 用 ， 开 发 者 能 够 使 用 自 定 
义 的 卡片 布局 创建 自 定 义 Notifications。 

Import 必 要 的 类 

为 了 引入 必要 的 包 ， 在 我 们 的 build.gradle 文件 中 加 入 如 下 内 容 : 


compile "com.android.support:support-v4:20.0.+" 


现在 我 们 的 项 目 能 够 访问 关键 的 包 ， 接 下 来 从 support library 中 引入 必要 的 类 : 


import android.support.v4.app.NotificationCompat; 
import android.support.v4.app.NotificationManagerCompat; 
import android.support.v4.app.NotificationCompat.WearableExtender; 


i$ it Notification Builder] # Notification 


v4 support library 能 够 让 开发 者 使 用 最 新 的 特性 去 创建 Notification， 诸 如 action 按钮 和 大 的 图 
标 ， 而 且 兼 容 Android1.6 (APllevel4) 及 以 上 的 版 本 。 


为 了 通过 support library 创 建 一 个 Notification， 我 们 需要 创建 一 个 NotificationCompat.Builder 
的 实例 ， 然 后 通过 将 该 实例 传 给 notify()) 来 发 出 Notification。 例 如 : 


int notificationId = 001; 

// Build intent for notification content 

Intent viewIntent - new Intent(this, ViewEventActivity.class); 

viewIntent.putExtra(EXTRA EVENT ID, eventId); 

PendingIntent viewPendingIntent - 
PendingIntent.getActivity(this, 0, viewIntent, 0); 


NotificationCompat.Builder notificationBuilder - 
new NotificationCompat.Builder(this) 
.setsmallIcon(R.drawable.ic event) 
.setContentTitle(eventTitle) 
.setContentText(eventLocation) 
.setContentIntent(viewPendingIntent); 


// Get an instance of the NotificationManager service 
NotificationManagerCompat notificationManager - 
NotificationManagerCompat.from(this); 


// Build the notification and issues it with notification manager. 
notificationManager.notify(notificationId, notificationBuilder.build()); 


当 该 Notification 出 现在 手持 设备 上 时 ， 用 户 能 够 通过 触摸 Notification 来 触发 之 前 通过 
setContentlntent() 设 置 的 Pendinglntent。 当 该 Notification 出 现在 可 穿戴 设备 上 时 ， 用 户 能 够 
通过 向 左 滑动 该 Notification 显 示 Open 的 action， 点 击 这 个 action 能 够 激活 手持 设备 上 的 
Intent ° 


Ate Actioniz 4a 


除了 通过 setContentintent()) 定义 的 主要 内 容 action 之 外 ， 我 们 还 可 以 通过 传递 一 个 
Pendinglntent 给 addAction()) 来 添加 其 它 action。 


Archive 





例如 ， 下 面 的 代码 展示 了 创建 一 个 同 之 前 相仿 的 Notification， 只 不 过 添加 了 一 个 在 地 图 上 查 
看 事件 位 置 的 action » 


// Build an intent for an action to view a map 

Intent mapIntent - new Intent(Intent.ACTION VIEW); 

Uri geoUri = Uri.parse("geo:0,0?q-" + Uri.encode(location)); 

mapIntent.setData(geoUri); 

PendingIntent mapPendingIntent - 
PendingIntent.getActivity(this, 0, mapIntent, 0); 


NotificationCompat.Builder notificationBuilder - 
new NotificationCompat.Builder(this) 
.setsmallIcon(R.drawable.ic event) 
.setContentTitle(eventTitle) 
.setContentText(eventLocation) 
.setContentIntent(viewPendingIntent) 
.addAction(R.drawable.ic map, 

getString(R.string.map), mapPendingIntent); 


在 手持 设备 上 ，action 表 现 为 在 Notification 上 附加 的 一 个 额外 按钮 。 而 在 可 穿戴 设备 上 ， 
action 表 现 为 Notification 去 滑 后 出 现 的 大 按钮 。 当 用 户 点 击 action 时 ， 能 够 触发 手持 设备 上 对 
应 的 intent 。 


Tip : 如 果 我 们 的 Notification 包含 了 一 个 "回复 "的 action( 例 如 短信 类 app)， 我 们 可 以 通过 
支持 直接 从 Android 可 穿戴 设 备 返回 的 语音 输入 ， 来 加 强 该 功能 的 体验 。 更 多 信息 ， 详 见 
在 Notification 中 接收 语音 输入 。 


可 穿戴 式 独 有 的 Actions 


如 果 开 发 者 想 要 可 穿戴 式 设 备 上 的 action 与 手持 式 设 备 不 一 样 的 话 ， 可 以 使 用 
WearableExtenderaddAction())， 一 旦 我 们 通过 这 种 方式 添加 了 action， 可 穿戴 式 设备 便 不 会 
显示 任何 其 他 通过 NotificationCompat.BuilderaddAction()) 添加 的 action。 这 是 因为 ， 只 有 通 
过 WearableExtender.addAction()) 添加 的 action 才 能 只 在 可 穿戴 设备 上 显示 且 不 在 手持 式 设 
备 上 显示 。 


// Create an intent for the reply action 
Intent actionIntent - new Intent(this, ActionActivity.class); 
PendingIntent actionPendingIntent - 
PendingIntent.getActivity(this, 0, actionIntent, 
PendingIntent.FLAG UPDATE CURRENT); 


// Create the action 
NotificationCompat.Action action - 
new NotificationCompat.Action.Builder(R.drawable.ic action, 
getString(R.string.label, actionPendingIntent)) 
.build(); 


// Build the notification and add the action via WearableExtender 
Notification notification - 
new NotificationCompat.Builder(mContext) 

.setSmallIcon(R.drawable.ic message) 
.setContentTitle(getString(R.string.title)) 
.setContentText(getString(R.string.content)) 
.extend(new WearableExtender().addAction(action)) 
.build(); 


添加 一 个 Big View 


开发 者 可 以 在 Notification 中 通过 添加 某 种 "big view" 风 格 来 插入 扩展 文本 。 在 手持 式 设 备 上 ， 
用 户 能 够 通过 展开 Notification 看 见 big view 的 内 容 。 在 可 穿戴 式 设备 上 ，big view 内 容 是 默认 
可 见 的 。 
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可 以 通过 NotificationCompat.Builder *t $38] setStyle())， 并 设置 参数 为 BigTextStyle 或 
InboxStyle 的 实例 ， 从 而 将 扩展 内 容 添加 到 Notification 中 。 


比如 ， 下 面 的 代码 为 事件 Notification 添加 了 一 个 NotificationCompat.BigTextStyle 的 实例 ， 
目的 是 为 了 包含 完整 的 事件 描述 (这 能 够 包含 比 setContentText()) 提供 的 空间 所 能 容纳 的 字数 
更 多 的 文字 )。 


// Specify the 'big view' content to display the long 

// event description that may not fit the normal content text. 
BigTextStyle bigStyle = new NotificationCompat.BigTextStyle(); 
bigStyle.bigText(eventDescription); 


NotificationCompat.Builder notificationBuilder - 
new NotificationCompat.Builder(this) 
.setsmallIcon(R.drawable.ic event) 
.setLargeIcon(BitmapFractory.decodeResource( 
getResources(), R.drawable.notif background)) 
.setContentTitle(eventTitle) 
.setContentText(eventLocation) 
.setContentIntent(viewPendingIntent) 
.addAction(R.drawable.ic map, 
getString(R.string.map), mapPendingIntent) 
.setStyle(bigStyle); 


要 注意 的 是 ， 开 发 者 可 以 通过 setLargelcon()) 方法 为 任何 Notification 添加 一 个 大 图 标 。 但 
是 ， 这 些 图 标 在 可 穿戴 设备 上 会 显示 成 大 的 背景 图 片 ， 并 且 由 于 这 些 图 标 会 被 放大 以 适应 可 
穿戴 设备 的 屏幕 ， 导 致 这 些 图 标 显示 的 效果 不 好 。 想 要 为 Notification 添加 一 个 可 穿戴 设备 适 


用 的 背景 图 片 ， 请 看 下 面 一 小 节 为 Notification 添加 可 穿戴 式 特性 。 更 多 关于 大 图 片 在 
Notification 上 的 设计 ， 详 见 Design Principles of Android Wear ° 


为 Notification 添 加 可 穿戴 式 特 性 


如 果 我 们 需要 为 Notification 添加 一 些 可 穿戴 式 的 特性 设置 ， 比 如 制定 额外 的 内 容 页 ， 或 者 让 
用 户 通 过 语音 pene > 那么 我 们 可 以 使 用 NotificationCompat.WearableExtender 来 制 
定 这 些 设 置 。 为 了 适用 这 个 API， 我 们 需要 : 


.创建 一 个 WearableExtender 的 实例 ， 为 Notification 设置 可 穿戴 设备 独 有 的 特性 。 
2. 创建 一 个 NotificationCompat.Builder 的 实例 ， 就 像 本 课程 先前 所 说 的 ， 设 置 需要 的 
Notification 属性 。 
3. 调用 Notification 上 的 extend()) 并 将 WearableExtender 传 进 该 方法 。 这 在 Notification 
上 应 用 了 可 穿戴 设备 的 选项 。 
4. 调用 build()) 去 构建 一 个 Notification ° 


例如 ， 以 下 代码 调用 setHintHidelcon()) 方法 把 应 用 的 图 标 从 Notification 卡片 上 删 掉 。 


// Create a WearableExtender to add functionality for wearables 
NotificationCompat.WearableExtender wearableExtender = 
new NotificationCompat.WearableExtender() 
.setHintHideIcon(true) 
.setBackground(mBitmap); 


// Create a NotificationCompat.Builder to build a standard notification 
// then extend it with the WearableExtender 
Notification notif - new NotificationCompat.Builder(mContext) 
.setContentTitle("New mail from " + sender) 
.setContentText(subject) 
.setsmallIcon(R.drawable.new mail) 
.extend(wearableExtender) 
.build(); 


setHintHidelcon()) 和 setBackground()) 这 两 个 方法 是 NotificationCompat.WearableExtender 
可 用 的 新 Noticication 特性 的 两 个 例子 。 


Note : setBackground()) 中 使 用 的 位 图 在 不 滚动 的 背景 下 应 该 是 400x400 89 PHF > A 
支持 视差 滚动 的 背景 下 应 该 是 640x640。 将 这 些 位 图 放 在 res/drawable-nodpi 目录 下 。 
将 可 穿戴 Notification 中 使 用 的 其 它 不 是 位 图 的 资源 放 到 res/drawable-hdpi 目录 ， 例 如 
setContentlcon()) 用 到 的 那些 资源 。 


如 果 开 发 者 需要 稍 后 去 读 取 可 穿戴 特性 的 设置 ， 可 以 使 用 设置 相应 的 get 方 法 ， 该 例子 通过 调 
用 getHintHidelcon()) 去 获取 当前 Notification 是 否 隐藏 了 图 标 。 


NotificationCompat.WearableExtender wearableExtender = 
new NotificationCompat.WearableExtender(notif); 
boolean hintHideIcon - wearableExtender.getHintHideIcon(); 


传递 Notification 


如 果 开 发 者 想 要 传递 自己 的 Notification * 744% NotificationManagerCompat 的 API 代 替 
NotificationManager : 


// Get an instance of the NotificationManager service 
NotificationManagerCompat notificationManager - 
NotificationManagerCompat.from(mContext); 


// Issue the notification with notification manager. 
notificationManager.notify(notificationId, notif); 


如 果 开 发 者 使 用 了 framework 中 的 NotificationManager > #2 
NotificationCompat.WearableExtender 中 的 一 些 特性 就 会 失效 ， 所 以 ， 请 确保 使 用 
NotificationManagerCompat ° 


下 一 课 : 在 Notifcation 中 接收 语音 输入 


在 Notifcation 中 接收 语音 输入 


编写 :Wangyachen - 原 


x-:http://developer.android.com/training/wearables/notifications/voice-input.html 


如 果 手 持 式 设 备 上 的 Notification 包 含 了 一 个 输入 文本 的 action， 比 如 回复 邮件 ， 那 么 

action 正 常情 况 下 应 该 会 调 起 一 个 activity 让 用 户 进行 输入 。 但 是 ， 当 这 aa a R 
式 设 备 上 时 ， 是 没有 键盘 可 以 让 用 户 进行 输入 的 ， 所 以 开发 者 应 该 让 用 户 指 定 一 个 反馈 或 者 
通过 Remotelnput 预 先 设 定好 文本 信息 。 


当 用 户 通 过 语音 或 者 选择 可 见 的 消息 进行 回复 时 ， 系 统 会 将 文本 的 反馈 信息 与 开发 者 指定 的 
Notification 中 的 action iy A Intent 进 行 绑 定 ， 并 且 将 该 intent 发 送 给 手持 设 和 中 的 app。 


Note : Android 模 拟 器 并 不 支持 语音 输入 。 如 果 使 用 可 穿戴 式 设 备 的 模拟 器 的 话 ， 可 以 打 
开 AVD 设 置 中 的 Hardware keyboard present， 实 现 用 打字 代替 语音 。 
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定义 语音 输入 


为 了 创建 一 个 支持 语音 输入 的 action， 需 要 创建 一 个 Remotelnput.Builder 的 实例 ， 将 其 加 到 
Notification 的 action 中 。 这 个 类 的 构造 函数 接受 一 个 String 类 型 的 参数 ， 系 统 用 这 个 参数 作为 
语音 输入 的 key， 后 面 我 们 会 用 这 个 key 来 取得 在 手持 设备 中 输入 的 文本 。 


举 个 例子 ， 下 面 展示 了 如 何 创建 一 个 Remotelnput 对 象 ， 其 中 ， 该 提供 了 一 个 用 于 提示 语音 输 
入 的 自 定义 label。 


// Key for the string that's delivered in the action's intent 
private static final String EXTRA VOICE REPLY = "extra voice reply"; 


String replyLabel - getResources().getString(R.string.reply label); 


RemoteInput remoteInput - new RemoteInput.Builder(EXTRA VOICE REPLY) 
.setLabel(replyLabel) 
.build(); 


添加 预先 设 定 的 文本 反馈 


IN 


除了 要 打开 语音 输入 支持 之 外 ， 开 发 者 还 可 以 提供 多 达 5 条 的 文本 反馈 ， 这 样 用 户 可 以 直接 选 
择 实 现 快速 回复 。 该 功能 可 通过 调用 setChoices()) 并 传递 一 个 String 数 组 实现 。 





& 
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这 


举 个 例子 ， 可 以 用 resource 数 组 的 方式 定义 这 些 


res/values/strings.xml 


<?xml version="1.0" encoding="utf-8"?> 
<resources> 
<string-array name="reply_choices"> 
<item>Yes</item> 
<item>No</item> 
<item>Maybe</item> 
</string-array> 


</resources> 


然后 ， 卉 充 String 数组 ， 并 将 其 添加 到 Remotelnput 中 : 


public static final EXTRA VOICE REPLY = "extra voice reply"; 


String replyLabel - getResources().getString(R.string.reply label); 
String[] replyChoices - getResources().getStringArray(R.array.reply choices); 


RemoteInput remoteInput - new RemoteInput.Builder(EXTRA VOICE REPLY) 
.setLabel(replyLabel) 
.setChoices(replyChoices) 
.build(); 


添加 语音 输入 作为 Notification 的 action 


为 了 实现 设置 语音 输入 ， 可 以 把 Remotelnput 对 象 通过 addRemotelnput()) 设 置 到 一 个 action 
中 。 然 后 我 们 可 以 将 这 个 action 应 用 到 Notification 中 ， 例 如 : 


// Create an intent for the reply action 
Intent replyIntent - new Intent(this, ReplyActivity.class); 
PendingIntent replyPendingIntent - 
PendingIntent.getActivity(this, 0, replyIntent, 
PendingIntent.FLAG UPDATE CURRENT); 


// Create the reply action and add the remote input 
NotificationCompat.Action action - 
new NotificationCompat.Action.Builder(R.drawable.ic reply icon, 
getString(R.string.label, replyPendingIntent)) 
.addRemoteInput(remoteInput) 
.build(); 


// Build the notification and add the action via WearableExtender 
Notification notification - 
new NotificationCompat.Builder(mContext) 

.setSmallIcon(R.drawable.ic message) 
.setContentTitle(getString(R.string.title) ) 
.setContentText(getString(R.string.content)) 
.extend(new WearableExtender().addAction(action)) 
.build(); 


// Issue the notification 

NotificationManagerCompat notificationManager - 
NotificationManagerCompat.from(mContext); 

notificationManager.notify(notificationId, notification); 


当 程 序 发 出 这 个 Notification 的 时 候 ， 用 户 在 可 穿戴 设备 上 左 滑 便 可 以 看 到 reply 的 按钮 。 


将 语音 输入 转化 为 String 


通过 调用 getResultsFromlntent()) 方 法 ， 将 返回 值 放 在 "Reply" 的 action 指 定 的 intent 中 ， 开 发 者 
以 在 回复 的 action 的 intent 中 指 接收 到 用 户 转录 后 的 消息 。 该 方法 返回 的 


包含 了 文本 反馈 的 Bundle。 我 们 可 以 通过 查询 Bundle 中 的 内 容 来 获得 这 条 反馈 。 
Note : 请 不 要 使 用 Intent.getExtras()) 来 获取 语音 输入 的 结果 ， 因 为 语音 输入 的 内 容 是 存 
B kk X 


储 在 ClipData 中 的 。getResultsFromlntent()) 提 供 了 一 条 很 方便 的 途径 来 接收 字符 数组 类 
型 的 语音 信息 ， 并 且 不 需要 经 过 ClipData 自 身 的 调用 。 


下 面 的 代码 展示 了 一 个 接收 intent， 并 且 返 回 语音 反馈 信息 的 方法 ， 该 方法 是 依据 之 前 例子 中 
的 EXTRA_VOICE_REPLY 作为 key 进 行 检索 : 


在 Notifcation 中 接收 语音 输入 


JER 
* Obtain the intent that started this activity by calling 
* Activity.getIntent() and pass it into this method to 
* get the associated voice input string. 
多 


private CharSequence getMessageText(Intent intent) { 
Bundle remoteInput - RemoteInput.getResultsFromIntent(intent); 
if (remoteInput != null) { 
return remoteInput.getCharSequence(EXTRA VOICE REPLY); 


} 


return null; 


下 一 课 : 为 Notification 添 加 页 面 


504 


为 Notification 添加 页 面 


编写 :Wangyachen - 原 
文 :http://developer.android.com/training/wearables/notifications/pages.html 


当 开 发 者 想 要 在 不 需要 用 户 在 他 们 的 手机 上 打开 app 的 情况 下 ， 还 可 以 允许 表达 更 多 的 信息 ， 


那么 开发 者 可 以 在 可 穿戴 设备 上 的 Notification 中 添加 一 个 或 多 个 的 页 面 。 添 加 的 页 面 会 马上 
出 现在 主 Notification 卡片 的 右边 。 





Bring some french 
bread, good cheese, 
and a bottle of red. 


10 mins 
Picnic with Rachel 


arl 


为 了 创建 一 个 拥有 多 个 页 面 的 Notification， 开 发 者 需要 : 


i" 


3i 3¢ NotificationCompat.Builderé] € Z. Notification (首页 ) ， 以 开发 者 想 要 的 方式 使 其 出 
现在 手持 设备 上 。 

通过 NotificationCompat.Builder 为 可 穿戴 设备 添加 更 多 的 页 面 。 

通过 addPage()) 方 法 将 这 些 页 面 应 用 到 主 Notification 中 ， 或 者 通过 addPages()) 将 多 个 
页 面 添加 到 一 个 Collection ° 


举 个 例子 ， 以 下 代码 为 Notification 添 加 了 第 二 个 页 面 : 


// Create builder for the main notification 

NotificationCompat.Builder notificationBuilder - 
new NotificationCompat.Builder(this) 
.setsmallIcon(R.drawable.new message) 
.setContentTitle("Page i") 
.setContentText("Short message") 
.setContentIntent(viewPendingIntent); 


// Create a big text style for the second page 
BigTextStyle secondPageStyle = new NotificationCompat.BigTextStyle(); 
secondPageStyle.setBigContentTitle("Page 2") 

sbuzgrext( A lot of text...) 


// Create second page notification 
Notification secondPageNotification - 
new NotificationCompat.Builder(this) 
.setStyle(secondPageStyle) 
.build(); 


// Add second page with wearable extender and extend the main notification 
Notification twoPageNotification - 
new WearableExtender() 
.addPage(secondPageNotification) 
.extend(notificationBuilder) 
.build(); 


// Issue the notification 
notificationManager - 

NotificationManagerCompat.from(this); 
notificationManager.notify(notificationId, twoPageNotification); 


下 一 课 : A Stack£ Zr X X zs Notifications 


将 Notification 2x — & 


编写 :wangyachen - R x : 
http://developer.android.com/training/wearables/notifications/stacks.html 


当 为 手持 式 设备 创建 Notification 时 ， 开 发 者 应 该 将 多 个 相似 的 Notification 合 并 成 一 个 概括 式 的 
Notification。 例 如 ， 如 果 app 创 建 了 一 系列 接收 短信 的 Notification， 开 发 者 不 应 该 将 多 于 一 个 
Notification 显 示 到 可 穿戴 设备 上 一 一 当 接收 到 多 于 一 条 消息 的 时 候 ， 用 一 个 Notification 提 供 一 
个 摘要 ， 比 如 "2 条 新 消息 " 。 


尽管 如 此 ， 一 个 概括 式 的 Notification 在 可 穿戴 设备 上 并 不 是 很 有 用 处 ， 因 为 用 户 不 能 在 可 穿 
戴 设备 上 阅读 每 条 消息 的 详细 内 容 (他 们 必须 在 手持 式 设 备 上 打开 相应 的 app 才 能 看 到 更 多 信 
息 )。 所 以 对 可 穿戴 设备 而 言 ， 开 发 者 应 该 将 所 有 的 Notification 都 集中 起 来 ， 放 成 一 熏 。 这 得 
Notification 以 一 张 卡片 的 形式 显示 出 来 ， 用 户 可 以 将 它 展 开 ， 分 别 看 到 每 个 Notification 的 详细 
内 容 。 通 过 新 方法 setGroup()) 能 够 实现 该 功能 ， 同 时 ， 也 能 保持 手持 式 设备 上 显示 为 一 条 概 
括 式 的 Notification ° 
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将 每 个 Notification 添 加 到 一 个 群 组 中 


为 了 创建 一 个 stack， 可 以 对 每 个 想 要 放 入 该 stack 的 Notification 调 用 setGroup())， 并 且 指 定 一 
个 group key。 然 后 调用 notify()) 将 其 发 送 至 可 穿戴 设备 上 。 


final static String GROUP KEY EMAILS = "group key emails"; 


// Build the notification, setting the group appropriately 
Notification notif = new NotificationCompat.Builder(mContext) 
.setContentTitle("New mail from " + senderi) 

.setContentText(subject1) 
.setSmalliIcon(R.drawable.new_mail); 
. setGroup(GROUP_KEY_EMAILS) 
.build(); 


// Issue the notification 

NotificationManagerCompat notificationManager - 
NotificationManagerCompat.from(this); 

notificationManager.notify(notificationId1, notif); 


稍 后 ， 当 开发 者 创建 另 一 个 Notification 的 时 候 ， 指 定 同样 的 group key。 当 在 调用 notify()) 的 时 
候 ， 这 个 Notification 就 会 出 现在 之 前 那个 Notification 的 同一 个 stack 中 ， 而 非 新 建 一 张 卡 片 。 


Notification notif2 = new NotificationCompat.Builder(mContext) 
.setContentTitle("New mail from " + sender2) 
.setContentText(subject2) 
.setSmallIcon(R.drawable.new mail); 
.SetGroup(GROUP KEY EMAILS) 

.build(); 


notificationManager.notify(notificationId2, notif2); 


在 默认 的 情况 下 ，Notification 的 排列 顺序 由 开发 者 添加 的 先后 顺序 决定 ， 最 近 的 Notification 会 
被 放置 在 最 顶端 。 你 可 以 通过 setSortKey()) 来 修改 Notification 的 排 顺 序 。 


添加 概括 式 Notification 


在 手持 设备 上 提供 一 个 概括 式 的 Notification 是 很 重要 的 。 因 此 除了 要 将 每 条 单独 的 Notification 
放置 在 同一 个 stack group 中 ， 还 需要 添加 一 个 概括 式 的 Notification， 并 对 其 调 
用 setGroupSummary()) 即 可 实现 。 


该 Notification 并 不 会 出 现在 可 穿戴 设备 上 的 stack 中 ， 只 会 出 现在 手持 式 设备 上 。 


MESO mu wc 
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Bitmap largeIcon = BitmapFactory.decodeResource(getResources(), 
R.drawable.ic large icon); 


// Create an InboxStyle notification 
Notification summaryNotification - new NotificationCompat.Builder(mContext) 
.setContentTitle("2 new messages") 
.setsmallIcon(R.drawable.ic small icon) 
.setLargelIcon(largeIcon) 
.setStyle(new NotificationCompat.InboxStyle() 
.addLine("Alex Faaborg Check this out") 
.addLine("Jeff Chang Launch Party") 
.setBigContentTitle("2 new messages") 
.setSummaryText ("johndoeQgmail.com")) 
.setGroup(GROUP KEY EMAILS) 
.setGroupSummary(true) 
.build(); 


notificationManager.notify(notificationId3, summaryNotification); 


该 Notification 使 用 了 NotificationCompat.InboxStyle， 这 个 style 能 够 让 开发 者 很 轻松 地 创建 邮 
件 或 者 短信 app 的 Notifications。 开 发 者 可 以 对 概括 式 Notification 使 用 这 个 style， 或 
者 NotificationCompat 中 定义 的 其 他 style， 或 者 不 使 用 任何 style 也 可 以 。 


Tip : 如 果 想 要 和 上 面 截 图 中 一 样 的 设计 文本 ， 请 参考 Styling with HTML markup 和 
Styling with Spannables ° 


概括 式 Notification 能 够 在 不 显示 在 可 穿戴 设备 上 的 前 提 下 做 到 影响 可 穿戴 设备 上 的 
Notification。 当 开发 者 创建 一 个 概括 式 Notification 时 ， 可 以 利 

用 NotificationCompat.WearableExtender， 调 用 setBackground()) 或 者 addAction()) 为 可 穿戴 
设备 上 的 整个 stack 设 置 一 个 背景 图 片 或 者 一 个 action。 以 下 代码 展示 了 如 何 为 整个 stack 设 置 


ab * 
d: 


Bitmap background = BitmapFactory.decodeResource(getResources(), 
R.drawable.ic background); 


NotificationCompat.WearableExtender wearableExtender - 
new NotificationCompat.WearableExtender() 
. setBackground( background) ; 


// Create an InboxStyle notification 

Notification summaryNotificationWithBackground = 
new NotificationCompat.Builder(mContext) 
.setContentTitle("2 new messages") 


.extend(wearableExtender) 
.setGroup(GROUP KEY EMAILS) 
.setGroupSummary(true) 
.build(); 


创建 可 穿戴 的 应 用 


编写 :kesenhoo - 原文 :http://developer.android.com/training/wearables/apps/index.html 


可 穿戴 应 用 直接 运行 在 穿戴 设备 上 ， 应 用 可 以 直接 访问 例如 传感器 paler 文 样 的 硬件 。 这 些 
应 用 和 一 般 的 Android 应 用 的 基础 部 分 是 一 致 的 ， 只 是 在 设计 与 可 用 性 还 有 一 些 特殊 功能 上 有 
比较 大 差异 。 手 持 设 备 与 可 穿戴 设备 上 的 应 用 主要 有 下 面 的 一 些 差异 : 


e 系统 会 强制 执行 超时 机 制 。 如 果 我 们 显示 了 一 个 Activity， 用 户 并 没有 进行 操作 ， 设 备 会 
进入 睡眠 状态 。 当 设备 唤醒 时 ， 穿 戴 设 备 会 显示 主 界面 而 不 是 刚才 的 activity。 如 果 我 们 
想 要 持续 的 显示 一 些 东 西 ， 请 使 用 notification 来 奉 代 。 

e 相 比 起 手持 设备 的 应 用 ， 可 穿戴 应 用 的 界面 相对 更 小 ， 功 能 也 相对 更 少 。 他 仅仅 包含 了 
那些 对 于 可 穿戴 有 意义 的 功能 ， 这 些 功能 通常 是 手持 设备 的 一 个 子 集 。 通 常 来 说 ， 我 们 
应 该 尽 可 能 的 把 运行 操作 搬 到 手持 设备 上 ， 然 后 发 送 操作 结果 到 可 穿戴 设备 。 

e 用 户 不 会 直接 将 应 用 下 载 到 可 穿戴 设备 上 进行 安装 。 相 反 ， 我 们 将 可 穿戴 设备 应 用 打包 
到 手持 设备 应 用 里 。 当 用 户 安 装 手持 设备 的 应 用 时 ， 系 统 会 自动 安装 可 穿戴 应 用 。 然 
而 ， 为 了 开发 便利 ， 我 们 还 是 可 以 直接 安装 应 用 到 可 穿戴 设备 。 

。 可 穿戴 应 用 可 以 使 用 大 多 数 的 标准 Android APls， 除 了 下 面 的 以 外 : 


o android.webkit 
o android.print 
o android.app.backup 
o android.appwidget 
e android.hardware.usb 
在 使 用 某 个 API 之 前 ， 我 们 可 以 通过 执行 hasSystemFeature()) 来 判断 可 穿戴 应 用 是 否 支 


持 茶 个 功能 。 


Note: 我 们 推荐 使 用 Android Studio 来 开发 Android Wear 的 应 用 ， 因 为 它 提 供 了 建立 工 
程 ， 添 加 库 依 赖 ， 打 包 程 序 等 在 ADT 上 没有 的 功能 。 下 面 的 培训 课程 的 前 提 是 假设 你 已 
经 在 使 用 Android Studio F ° 


Lessons 


e 创建 并 运行 可 穿戴 应 用 (Creating and Running a Wearable App) 


学 习 如 何 创建 一 个 包含 了 可 穿戴 与 手持 应 用 的 Android Studio 工 程 。 学 习 如 何在 设备 或 者 
模拟 器 上 运行 应 用 。 


创建 自 定 义 的 布局 (Creating Custom Layouts) 


学 习 如 何 为 notification 与 activity 创 建 并 显示 一 个 自 定 义 的 布局 


e 添加 语音 功能 (Adding Voice Capabilities) 


学 习 如 何 使 用 语音 指令 启动 一 个 activity， 学 习 如 何 启动 系统 语音 识别 应 用 来 获取 用 户 的 


语音 输入 。 
e 打包 可 穿戴 应 用 (Packaging Wearable Apps) 


学 习 如 何 把 可 穿戴 应 用 打包 到 手持 应 用 上 。 这 使 得 系统 能 够 在 安装 Google Play 商店 上 的 
手持 应 用 时 自动 安装 可 穿戴 应 用 。 


e 通过 蓝牙 进行 调试 (Debugging over Bluetooth) 


学 习 如 何 通过 蓝牙 而 不 是 USB 来 调试 可 穿戴 应 用 。 


创建 并 运行 可 穿戴 应 用 


编写 :kesenhoo - J. 
文 :http://developer.android.com/training/wearables/apps/creating.html 


可 穿戴 应 用 可 以 直接 运行 在 可 穿戴 的 设备 上 。 拥 有 访问 类 似 传 感 器 的 硬件 权限 ， 还 有 操作 
activity，services 等 权限 。 


当 我 们 想 要 将 可 穿戴 设备 应 用 发 布 到 Google Play 商店 时 ， 我 们 需要 有 该 应 用 的 配套 手持 设备 
应 用 。 因 为 可 穿戴 设备 不 支持 Google Play 商 店 ， 所 以 当 用 户 下 载 配套 手持 设备 应 用 的 时 候 ， 
会 自动 安装 可 穿戴 应 用 到 可 穿戴 设备 上 。 手 持 设备 应 用 还 可 以 用 来 处 理 一 些 繁 重 的 任务 、 网 

络 指令 或 者 其 它 工作 ， 和 发 送 操作 结果 给 可 穿戴 设备 。 


这 节 课 会 介绍 如 何 安装 一 个 设备 或 者 模拟 器 ， 和 如 何 创 建 一 个 包含 了 手持 应 用 与 可 穿戴 应 用 
的 工程 。 


升级 SDK 


在 开始 建立 可 穿戴 设备 应 用 前 ， 必 须 : 
。 将 SDK 工 具 升 级 到 23.0.0 或 者 更 高 的 版 本 
升级 后 的 SDK 工 具 使 我 们 可 以 建立 和 测试 可 穿戴 应 用 。 
e 将 SDK 升 级 到 Android 4.4W.2(API 20) 或 者 更 高 
升级 后 的 平台 版 本 为 可 穿戴 应 用 提供 了 新 的 API。 


想 要 了 解 如 何 升级 SDK， 请 查看 Get the latest SDK tools ° 


搭建 Android Wear 模 拟 器 或 者 丨 机 设备 。 


我 们 推荐 在 监 机 上 进行 开发 ， 这 样 可 以 更 好 地 评估 用 户 体验 。 然 而 ， 模 拟 器 可 以 使 我 们 在 不 
同类 型 的 设备 屏幕 上 进行 模拟 ， 这 对 测试 来 说 非常 有 用 。 

$32 Android Wear 虚 拟 设备 

建立 Android Wear 虚 拟 设 备 需要 下 面 几 个 步骤 : 


1. 点 击 Tools > Android > AVD Manager ° 
2， 点 击 Create Virtual Device... ° 


i， 点 击 Category 列 表 的 Wear 选 项 。 
ii， 选 择 Android Wear Square 或 者 Android Wear Round ° 
iii. d: Nextiz4 © 
iv. 选择 一 个 release name (例如 ，KitKat Wear) ° 
v. 点 击 Next 按 钮 。 
vi. (FH) 改变 虚拟 设备 的 首选 项 。 
vii， 点 击 Finish 按 钮 。 
3. 局 动 模拟 器 : 
i， 选 择 我 们 刚才 创建 的 虚拟 设备 。 
ii， 点 击 Play 按钮 。 
ii， 等 待 模拟 器 初始 化 直到 显示 Android Wear 的 主 界面 。 
4. 匹配 手持 和 模拟 器 : 
i， 在 我 们 的 手持 设备 上 ， 从 Google Play 安装 Android Wear 应 用 。 
ii 通过 USB 将 手持 设备 连接 到 电脑 。 
ii， 切 换 AVD 的 通信 端口 到 已 连接 的 手持 设备 (每 次 连接 上 手持 设备 时 都 要 执行 这 个 步 


TR) : 


adb -d forward tcp:5601 tcp:5601 


iv. 局 动手 持 设备 上 的 Android Wear 应 用 ， 并 连接 到 模拟 器 。 
v. 点 击 Android Wear 应 用 右上 角 的 菜单 ， 选 择 Demo Cards 。 
Vi， 我 们 选择 的 卡片 会 义 Notification 的 形式 呈现 在 模拟 器 的 主页 上 。 


32 Android Wear & tu 
32 = Android Wear Ju » FLEE da JUA E 9I: 


1. 在 手持 设备 的 Google Play 上 安装 Android Wear A) » 
2. 按照 应 用 的 命令 指示 与 我 们 的 可 穿戴 设备 进行 配对 。 如 果 你 有 做 建立 hotification 的 操作 ， 
这 个 步骤 刚好 可 以 测试 这 一 功能 。 
3. 保持 Android Wear 应 用 在 手机 上 的 打开 状态 。 
4. 打开 Android Wear 设 备 的 adb 调 试 开关 。 
i. 选择 Settings > About。 
ii， 点 击 Build number 7 次 。 
ii， 右 滑 返 回 到 Setting 菜 单 。 
iv. 进入 屏幕 底部 的 Developer options。 
v. 点 击 ADB Debugging 来 打开 adb 。 
5. 通过 USB 连 接 可 穿戴 设备 到 电脑 上 ， 这 样 我 们 能 够 直接 安装 应 用 到 可 穿戴 设备 上 。 此 
时 ， 在 可 穿戴 设备 与 Android Wear 应 用 上 会 显示 一 个 消息 ， 提 示 是 否 允 许 进行 调试 。 
6. 在 Android Wear 应 用 上 ， 选 择 Always allow from this computer 并 且 点 击 OK。 


Android Studio 上 的 Android Tool 窗 口 可 以 显示 可 穿戴 设备 的 日 志 。 当 你 执行 adb devices 命 
令 的 时 候 ， 可 穿戴 设备 应 该 会 出 现在 该 窗口 中 。 


创建 工程 


在 开始 开发 之 前 ， 需 要 创建 一 个 包含 可 穿戴 应 用 与 手持 应 用 这 两 个 模块 的 工程 。 在 Android 
Studio 中 ， 点 击 File > New Project， 然 后 按照 创建 工程 的 指引 进行 操作 。 在 我 们 按照 安装 向 
导 操 作 的 过 程 中 ， 输 入 下 面 的 信息 


1. 在 Configure your Project 窗 口 里 ， 输 入 应 用 的 名 称 与 一 个 包 名 。 
2. 在 Form Factors 窗 口中 : 
o 勾 选 Phone and Tablet 并 在 Minimum SDK 下 拉 菜 单 中 选择 API19: Android 2.3 
(Gingerbread) ° 
o 4) Wear i+ Minimum SDK T 4 ¥ + 2 7#API 20: Android 4.4 (KitKat 
Wear) ° 
3. 在 第 一 个 Add an Activity 窗 口 ， 为 手机 应 用 添加 一 个 空白 的 activity 。 
4. 在 第 二 个 Add an Activity 窗 口 ， 为 可 穿戴 应 用 添加 一 个 空白 的 activity 。 


安装 向 导 完成 后 ，Andorid Studio 创 建 了 一 个 包含 mobile 与 wear 两 个 模块 的 工程 。 现 在 ， 
e 以 在 手持 设备 和 可 穿戴 设备 应 用 中 创建 activity，service，layout 等 。 在 手持 
应 用 里 面 ， 需 要 承担 大 部 分 繁重 的 任务 ， 例 如 网 络 请 求 ， 密 集 计 算 任 务 或 者 是 需要 大 量 用 户 
交互 的 任务 。 待 这 些 任 务 完 成 之 后 ， 通 常会 把 任务 结果 通过 notification 发 送 给 可 穿戴 设备 上 ， 
或 者 是 通过 同步 机 制 发 送 数据 给 可 穿戴 设备 。 


Note: 可 穿戴 模块 包含 了 一 个 "Hello World" 的 activity， 它 是 使 用 watchviewstub 类 。 该 类 
根据 设备 屏幕 是 圆 的 还 是 方 的 来 填充 一 个 布局 。 watchviewstub 类 是 wearable support 
library 中 的 一 个 UI 组 件 。 


和 可 穿戴 应 用 


在 开发 过 程 中 ， 我 们 可 以 像 安装 手持 应 用 一 样 直接 将 应 用 安装 到 可 穿戴 设备 上 。 可 以 使 用 adb 
install 命令 ， 也 可 以 使 用 Android Studio 上 面 的 Play 按 钮 。 


当 需 要 把 应 用 发 布 给 用 户 的 时 候 ， 需 要 把 可 穿戴 应 用 打包 到 手持 应 用 中 。 当 用 户 从 Google 
Play 安装 装 手 持 应 用 时 ， 连 接 上 的 可 穿戴 设备 会 自动 收 到 可 穿戴 应 用 。 


Note: 如 果 我 们 给 应 用 签名 是 debug key， 是 无 法 完成 自动 安装 可 穿戴 应 用 的 (只 有 
release key 才 可 以 ) 。 请 参考 打包 可 穿戴 应 用 获取 更 多 信息 ， 学 习 如 何 正 确 的 打包 。 


为 了 安装 "Hello World" 应 用 到 可 穿戴 设备 ， 在 Android Studiod 的 Run/Debug configuration 
的 下 拉 菜 单 中 选中 wear， 点 击 Play 按钮 即 可 。 在 可 穿戴 设备 上 会 显示 activity 并 打印 "Hello 
world!" 


include 正 确 的 libraries 


项 目 安装 向 导 会 自动 把 合适 的 模块 依赖 添加 到 对 应 的 build.gradle 文件 中 。 然 而 ， 这 些 依赖 
并 不 是 必须 的 ， 请 阅读 下 面 描述 判断 是 否 需要 这 些 依 赖 。 


Notifications 


The Android v4 support library (或 者 v13) 包 含 一 些 API， 这 些 API 可 以 将 手持 设备 应 用 已 经 存 
在 的 notification 扩 展 到 可 穿戴 应 用 上 。 


对 于 只 显示 在 可 穿戴 设备 上 的 notification( 这 意味 着 ， 他 们 是 由 直接 执行 在 可 穿戴 设备 上 的 app 
进行 处 理 的 )， 我 们 可 以 在 Wear 模 块 仅 仅 使 用 标准 APls (API Level 20) 并 且 把 Mobile 模 块 的 
support library 依 赖 移 除 。 


Wearable Data Layer 


可 穿戴 与 手持 设备 之 间 进 行 同步 与 发 送 数 据 需 要 使 用 Wearable Data Layer APIs, 这 需要 用 到 
最 新 版 本 的 Google Play Services。 如 果 我 们 不 需要 这 些 APls， 可 以 从 这 两 个 模块 中 把 这 部 分 
的 依赖 移 除 。 

Wearable Ul support library 

这 是 一 个 非 官 方正 式 的 library， 它 包含 了 为 可 穿戴 设备 设计 的 Ul 组 件 。 我 们 鼓励 你 在 你 的 应 用 
中 使 用 人 他们， 因为 这 些 组 件 是 最 佳 实践 的 例证 。 但 是 他 们 可 能 随时 发 生变 人 化。 然而， 如果 
library 有 更 新 ， 你 的 应 用 并 不 会 发 送 前 溃 ， 因 为 那些 代码 已 经 编译 到 你 的 应 用 中 了 。 为 了 获取 
更 新 包 中 新 的 功能 ， 你 只 需要 更 新 链接 到 新 的 版 本 并 相应 的 更 新 你 的 应 用 就 好 了 。 这 个 library 
只 是 在 你 需要 创建 可 穿戴 应 用 时 才 会 使 用 到 。 


在 下 一 节 课 ， 我 们 将 会 学 习 如 何 创 建 为 可 穿戴 设备 设计 的 布局 ， 同 时 学 习 如 何 使 用 各 种 语音 
action ° 


创建 自 定 义 的 布局 


编写 : kesenhoo - 原文 : 
http://developer.android.com/training/wearables/apps/layouts.html 


为 可 穿戴 设备 创建 布局 是 和 手持 设备 是 一 样 的 ， 除 了 我 们 需要 为 屏幕 的 尺寸 和 glanceability 进 
行 设 计 。 但 是 不 要 期 望 通过 搬迁 手持 应 用 的 功能 与 UI 到 可 穿戴 上 会 有 一 个 好 的 用 户 体验 。 仅 
仅 在 有 需要 的 时 候 ， 我 们 才 应 该 创建 自 定 义 的 布局 。 请 参考 可 穿戴 设备 的 design guidelines 学 
习 如 何 设计 一 个 优秀 的 可 穿戴 应 用 。 


创建 自 定 义 Notification 


通常 来 说 ， 我 们 应 该 在 手持 应 用 上 创建 好 notification， 然 后 让 它 自动 同步 到 可 穿戴 设备 上 。 这 
让 我 们 只 需要 创 人 ， 然 后 可 以 在 不 同类 型 的 设备 (不 仅仅 是 可 穿戴 设备 ， 也 包 
含 车 载 设备 与 电视 ) 上 进行 显示 ， 免 去 为 不 同 设备 进行 重新 设计 。 


如 果 标 准 的 notification 风 格 无 法 满足 我 们 的 需求 (例如 NotificationCompat.BigTextStyle 或 者 
NotificationCompat.InboxStyle)， 我 们 可 以 显示 一 个 使 用 自 定 义 布 局 的 activity。 我 们 只 可 以 在 
可 穿戴 设备 上 创建 并 处 理 自 定 义 的 notification， 同 时 系统 不 会 将 这 些 notification 同 步 到 手持 设 
备 上 。 


Note: 当 在 可 穿戴 设备 上 创建 自 定义 的 notification 时 ， 我 们 可 以 使 用 标准 notification API (API 
Level 20) ， 不 需要 使 用 Support Library。 


为 了 创建 自 定 义 的 notification， 步 又 如 下 : 
创建 布局 并 设置 这 个 布局 为 需要 显示 的 activity 的 content view: 
public void onCreate(Bundle bundle)( 


setContentView(R.layout.notification activity); 


j 


2. 为 了 使 得 activity 能 够 显示 在 可 穿戴 设备 上 ， 需 要 在 manifest 文 件 中 为 activity 定 义 必须 的 属 
性 。 我 们 需要 把 activity 声 明 为 exportable，embeddable 以 及 拥有 一 个 空 的 task affinity 。 
我 们 也 推荐 把 activity 的 主题 设置 为 Theme.DeviceDefault.Light 。 例 如 : 


«activity android:name="com.example.MyDisplayActivity" 
android:exported="true" 
android: allowEmbedded="true" 
android: taskAffinity="" 
android: theme="@android:style/Theme.DeviceDefault.Light" /> 


3. 为 activity 创 建 Pendinglntent， 例 如 : : 


Intent notificationIntent = new Intent(this, NotificationActivity.class); 
PendingIntent notificationPendingIntent - PendingIntent.getActivity(this, 0, notif 
icationIntent, 

PendingIntent.FLAG UPDATE CURRENT); 


4. 创建 Notification 并 执行 setDisplaylntent()) 方 法 ， 参 数 是 前 面 创 建 的 Pendinglntent。 当 用 
户 查 看 这 个 notification 时 ， 系 统 使 用 这 个 Pendinglntent 来 启动 activity。 
5. 使 用 notify()) 方 法 触发 notification ° 


Note: Z notification 呈现 在 主页 时 ， 系 统 会 根据 notification 的 语义 ， 使 用 一 个 标准 的 模板 
来 呈现 它 。 这 个 模板 可 以 在 所 有 的 表 瘟 上 进行 显示 。 当 用 户 往 上 滑动 hotification 时 ， 将 会 


看 到 为 这 个 notification 准 备 的 自 定义 的 activity。 


使 用 Wearable Ul 库 创建 布局 


当 我 们 使 用 Android Studio 的 工程 向 导 创建 一 个 Wearable 应 用 的 时 候 ， 会 自动 包含 Wearable 
Ul 库 。 你 也 可 以 通过 给 build.gradle 文件 添加 下 面 的 依赖 声明 把 库 文件 添加 到 项 目 : 


dependencies { 
compile fileTree(dir: 'libs', include: ['*.jar']) 
compile 'com.google.android.support:wearable:+' 
compile 'com.google.android.gms:play-services-wearable:+' 


这 个 库 文件 帮助 我 们 建立 为 可 穿戴 设备 设计 的 Ul。 更 详细 的 介绍 请 看 为 可 穿戴 设备 创建 自 定 
AX Ul? 


"Fé X — X Wearable UI P. 3x: X85 X : 


e BoxinsetLayout - 一 个 能 够 感知 屏幕 的 形状 并 把 子 控件 居中 摆 放 在 一 个 圆 形 屏幕 的 
FrameLayout ° 

e CardFragment - 一 个 能 够 可 拉 伸 ， 垂 直 可 滑动 卡片 的 fragment » 

e CircledlmageView - 一 个 圆 形 的 image view ° 

。 ConfirmationActivity - 一 个 在 用 户 完成 一 个 操作 之 后 用 来 显示 确认 动画 的 activity。 

e CrossFadeDrawable - 一 个 drawable。 该 drawable 包 含 两 个 子 drawable 和 提供 方法 来 调 
整 这 两 个 子 drawable 的 融合 方式 。 

e DelayedConfirmationView - 一 个 view。 提 供 一 个 圆 形 倒计时 器 ， 这 个 计时 器 通常 用 于 
在 一 段 短 暂 的 延迟 结束 后 自动 确认 某 个 操作 。 

e DismissOverlayView - 一 个 用 来 实现 长 按 消失 的 View。 

e DotsPagelndicator - 一 个 为 GridViewPager 提 供 的 指示 标记 ， 用 于 指定 当前 页 面相 对 于 
所 有 页 面 的 位 置 。 


GridViewPager - 一 个 可 以 横向 与 纵向 滑动 的 局 部 控制 器 。 你 需要 提供 一 个 


GridPagerAdapter 用 来 生成 显示 页 面 的 数据 。 
e GridPagerAdapter - 一 个 提供 给 GridqViewPager 显 示 页 面 的 adapter 。 


e FragmentGridPagerAdapter - 一 个 将 每 个 页 面 表示 为 一 个 fragment 的 
GridPagerAdapter 实 现 。 

e WatchViewStub - 一 个 可 以 根据 屏幕 的 形状 生成 特定 布局 的 类 。 

WearableListView - 一 个 针对 可 穿戴 设备 优化 过 后 的 ListView。 它 会 重 直 的 显示 列表 内 

容 ， 并 在 用 户 停止 滑动 时 自动 显示 最 靠近 的 ltem。 


Wear UI library API reference 

这 个 参考 文献 解释 了 如 何 详细 地 使 用 每 个 UI 组 件 。 查 看 Wear API reference documentation 了 
解 上 述 类 的 用 法 。 

为 用 于 Eclipse ADT T ZWearable UI 库 


如 果 你 正在 使 用 Eclipse ADT， 那 么 下 载 Wearable UI library 将 Wearable Ul 库 导入 到 你 的 工程 
当中 。 


Note: 我 们 推荐 使 用 Android Studio 来 开发 可 穿戴 应 用 。 


添加 语 首 功能 


编写 : kesenhoo - 原文 : http://developer.android.com/training/wearables/apps/voice.html 


语音 指令 是 可 穿戴 体验 的 一 个 重要 的 部 分 。 这 使 得 用 户 可 以 释放 双手 ， 快 速 发 出 指令 。 穿 吉 
提供 了 2 种 类 型 的 语音 操作 : 


© 系统 提供 的 


这 些 语 音 指令 都 是 基于 任务 的 ， 并 且 内 置 在 Wear 的 平台 内 。 我 们 在 activity 中 过 滤 我 们 想 
要 接收 的 指令 。 例 如 包含 "Take a note" 或 者 "Set an alarm" 的 指令 。 


e 应 用 提供 的 
Ed 


些 指令 都 是 基于 应 用 的 ， 我 们 需要 像 声 明 一 个 Launcher Icon 一 样 声明 这 些 指令 。 


这 些 语音 
用 户 通 过 说 "Start "来 使 用 那些 语音 指令 ， 然 后 会 启动 我 们 指定 启动 的 activity 。 


声明 系统 提供 的 语 彰 指 令 


Android Wear 平 台 基 于 用 户 的 操作 提供 了 一 些 语音 指令 ， 例 如 "Take a note" 或 者 "Set an 
alarm"。 用 户 发 出 想 要 做 的 操作 指令 ， 让 系统 启动 最 合适 的 activity 。 


当 用 户 说 出 语音 指令 时 ， 我 们 的 应 用 能 够 过 滤 出 用 于 启动 activity 的 intent。 如 果 我 们 想 要 启动 
一 个 在 后 台 执 行 任务 的 service， 需 要 显示 一 个 activity 作 为 视觉 线索 ， 并 且 在 该 activity 中 局 动 
service。 当 我 们 想 要 废弃 这 个 视觉 线索 时 ， 需 要 确保 执行 了 finish()。 


例如 ， 对 于 "Take a note" 的 指令 ， 声 明 下 面 这 个 intent filter 来 启动 一 个 名 为 MyNoteActivity 的 
activity: 


<activity android:name="MyNoteActivity"> 
<intent-filter> 
«action android:name="android.intent.action.SEND" /> 
«category android:name-"com.google.android.voicesearch.SELF NOTE" /> 
</intent-filter> 


</activity> 


下 面 列 出 了 Wear 平 台 支 持 的 语音 指令 : 
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Name Example 
Phrases 


Calla "OK , 
car/taxi Google, Action 
get mea com.google.android.gms.actions.RESERVE TAXI, RESERVATION 
taxi" 
"OK 
Google, 
call mea 
car" 
Takea "OK . 
note Google, Action 
take a android.intent.action.SEND 
note" Category 
com.google.android.voicesearch.SELF NOTE 
"OK 
Google, Extras 
note to android.content.Intent.EXTRA TEXT -a string with note body 
self" 
Set alarm "OK i 
setan android.intent.action.SET ALARM 
alarm for Extras 
8 AM android.provider.AlarmClock.EXTRA, HOUR - an integer with the hour of 
the alarm. 
"OK 
Google, android.provider.AlarmClock.EXTRA MINUTES - an integer with the 
wake me minute of the alarm 
up at 6 : : : 
aan (these 2 extras are optional, either none or both are provided) 
Set timer "Ok . 
Google, Action 
set a timer android.provider.AlarmClock.ACTION SET TIMER 
for 10 : Extras 
minutes android.provider.AlarmClock.EXTRA, LENGTH - an integer in the range of 
1 to 86400 (number of seconds in 24 hours) representing the length of the 
timer 
Start/Stop "OK . 
abikeride ^ Google, Action 
start vnd.google.fitness.TRACK 
cycling" Mime Type 
vnd.google.fitness.activity/biking 
"OK 
Google, Extras 
start my actionStatus -a string with the value ActiveActionStatus when starting 
bike ride" and CompletedActionStatus when stopping. 
"OK 
Google, 
stop 
cycling" 
Start/Stop “OK : 
a run Google, Action 
track my vnd.google.fitness.TRACK 
run" MimeType 
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添加 语音 功能 


vnd.google.fitness.activity/running 


"OK 
Google, Extras 
start actionStatus -a string with the value ActiveActionStatus when starting 
running" and CompletedActionStatus when stopping 
"OK 
Google, 
stop 
running" 
Start/Stop "OK : 
aworkout ^ Google, Action 
start a vnd.google.fitness.TRACK 
workout" MimeType 
vnd.google.fitness.activity/other 
"OK 
Google, Extras 
track my actionStatus -a string with the value ActiveActionStatus when starting 
workout" and CompletedActionStatus when stopping 
"OK 
Google, 
stop 
workout" 
Show "OK 
heartrate Google, Action 
what's my vnd.google.fitness.VIEW 
heath Mime Type 
rate? vnd. google. fitness.data_type/com. google. heart_rate. bpm 
"OK 
Google, 
what's my 
bpm?" 
Show step “OK 
count Google, Action 
how many vnd. google. fitness. VIEW 
stepshave Mime Type 
| taken? vnd.google.fitness.data type/com.google.step count.cumulative 
"OK 
Google, 
what's my 
step 
count?" 


关于 注册 intent 与 获取 intent extras 43 & > 4 4 A Common intents. 


声明 应 用 提供 的 语音 指令 


如 果 系 统 提供 的 语音 指令 无 法 满足 我 们 的 需求 ， 我 们 可 以 使 用 "Start MyActivityName" 语 音 指 
令 来 直接 启动 我 们 的 应 用 。 
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注册 一 个 "Start" 指 令 的 方法 和 注册 手持 应 用 上 的 Launcher Icon 是 一 样 的 。 除 了 在 launcher 里 
面 需 要 一 个 应 用 图 标 ， 而 我 们 的 应 用 需要 一 个 语音 指令 。 


为 了 指定 在 "Start" 指 令 之 后 需要 说 出 的 文本 , 我 们 需要 指定 想 要 启动 的 activity 的 label 属性 。 
例如 ， 下 面 的 intent filter 能 够 识别 "Start MyRunningApp" 语 音 指令 并 启动 startRunActivity ° 


<application> 
«activity android:name-"StartRunActivity" android: label="MyRunningApp"> 
<intent-filter> 
<action android:name="android.intent.action.MAIN" /> 
<category android:name="android.intent.category.LAUNCHER" /> 
</intent -filter> 
</activity> 
</application> 


获取 自由 格式 的 语音 输入 


除了 使 用 语音 指令 来 启动 activity 之 外 ， 我 们 也 可 以 执行 系统 内 置 的 语言 识别 activity 来 获取 用 
户 的 语音 输入 。 这 对 于 获取 用 户 的 输入 信息 非常 有 帮助 ， 例 如 执行 搜索 或 者 发 送 一 个 消息 。 


在 我 们 的 应 用 中 ， 使 用 ACTION_RECOGNIZE_SPEECH action 并 调 
用 startActivityForResult()。 这 样 可 以 启动 系统 语音 识别 应 用 ， 并 且 我 们 可 以 
在 onActivityResult() 中 处 理 返回 的 结果 : 


private static final int SPEECH REQUEST CODE = 0; 


// Create an intent that can start the Speech Recognizer activity 
private void displaySpeechRecognizer() { 
Intent intent - new Intent(RecognizerIntent.ACTION RECOGNIZE SPEECH); 
intent.putExtra(RecognizerIntent.EXTRA LANGUAGE MODEL, 
RecognizerlIntent.LANGUAGE MODEL FREE FORM); 
// Start the activity, the intent will be populated with the speech text 
startActivityForResult(intent, SPEECH REQUEST CODE); 


// This callback is invoked when the Speech Recognizer returns. 
// This is where you process the intent and extract the speech text from the intent. 
@Override 
protected void onActivityResult(int requestCode, int resultCode, 

Intent data) { 

if (requestCode == SPEECH REQUEST && resultCode == RESULT OK) { 
List<String> results = data.getStringArrayListExtra( 
RecognizerIntent.EXTRA RESULTS); 
String spokenText = results.get(0); 
// Do something with spokenText 


} 


super.onActivityResult(requestCode, resultCode, data); 


打包 可 穿戴 应 用 


编写 : kesenhoo - 原文 : 
http://developer.android.com/training/wearables/apps/packaging.html 


当 发 布 应 用 给 用 户 之 前 ， 我 们 必须 把 可 穿戴 应 用 打包 到 手持 应 用 内 。 因 为 用 户 不 能 直接 在 可 
穿戴 设备 上 浏览 并 安装 应 用 。 如 果 打 包 正 确 ， 当 用 户 下 载 手持 应 用 时 ， 系 统 会 自动 下 发 可 穿 
戴 应 用 到 配对 好 的 可 穿戴 设备 上 。 


Note: 如 果 开 发 时 签名 用 的 是 debug key， 这 个 功能 是 无 法 正常 工作 的 。 在 开发 时 ， 需 要 
使 用 adb install 命令 或 者 Android Studio 来 安装 可 穿戴 应 用 。 


使 用 Android Studio 打 色 


在 Android Studio 中 打包 可 穿戴 应 用 有 下 面 几 个 步骤 : 


1. 在 手持 设备 应 用 的 manifest 文 件 中 包括 所 有 在 可 穿戴 设备 应 用 manifest 文 件 中 声明 的 权 
限 。 例 如 ， 如 果 我 们 在 可 穿戴 应 用 中 指定 了 VIBRATE 权 限 ， 那 么 我 们 必须 将 该 权限 添加 
到 手持 设备 应 用 中 。 
2. 确保 可 穿戴 应 用 和 手持 应 用 都 有 相同 的 包 名 和 版 本 号 。 
3. 在 手持 应 用 的 buidl.gradle 文件 中 声明 一 个 Gradle 依 赖 用 于 指向 可 穿戴 应 用 : 
dependencies { 
compile 'com.google.android.gms:play-services:5.0.+@aar' 
compile 'com.android.support:support-v4:20.0.+'' 


wearApp project(':wearable') 


à 


4. 点 击 Build > Generate Signed APK...， 按 照 屏幕 上 的 指示 来 制定 我 们 的 release key 并 为 

我 们 的 app 进 行 签名 。Android Studio 将 签名 好 的 内 置 了 可 穿戴 应 用 的 手持 应 用 自动 导出 
到 工程 的 根 目 录 。 或 者 ， 我 们 可 以 使 用 Gradle wrapper 在 命令 行 下 为 在 可 穿戴 应 用 与 手持 
应 用 签名 。 为 了 能 够 正常 自动 推送 可 穿戴 应 用 ， 这 两 个 应 用 都 必须 签名 。 将 我 们 的 key 文 
件 位 置 和 凭证 保存 到 环境 变量 中 ， 然 后 如 下 运行 Gradle wrapper : 

./gradlew assembleRelease \ 

-Pandroid.injected.signing.store.file-$KEYFILE \ 

-Pandroid.injected.signing.store.password-$STORE PASSWORD \ 


-Pandroid.injected.signing.key.alias-$KEY ALIAS \ 
-Pandroid.injected.signing.key.password-$KEY PASSWORD 


分 别 为 可 穿戴 应 用 与 手持 应 用 进行 签名 


如 果 我 们 的 构建 过 程 需要 将 可 穿戴 应 用 的 签名 与 手持 应 用 的 分 开 ， 那 么 我 们 可 以 像 下 面 一 样 
在 手持 应 用 的 build.gradle 文件 中 声明 Gradle 规 则 。 从 而 襄 入 预先 签名 的 可 穿戴 应 用 : 


dependencies { 


wearApp files('/path/to/wearable app.apk') 
j 


我 们 可 以 以 任何 我 们 想 要 的 方式 为 手持 应 用 进行 签名 (可 以 是 Android Studio Build > 
Generate Signed APK... 的 方式 ， 也 可 以 是 Gradle signingconfig 规则 的 方式 ) ° 


手动 打包 


如 果 我 们 使 用 的 是 其 它 IDE 或 者 其 它 方法 来 构建 应 用 ， 我 们 仍然 可 以 手动 地 把 可 穿戴 应 用 打包 
到 手持 应 用 中 。 


1. 在 手机 应 用 的 manifest 文 件 中 包括 所 有 在 可 穿戴 设备 应 用 manifest 文 件 中 声明 的 权限 。 例 
如 ， 如 果 我 们 在 可 穿戴 应 用 中 指定 了 VIBRATE 权 限 ， 那 么 我 们 必须 将 该 权限 添加 到 手机 
应 用 中 。 
2. 确保 可 穿戴 应 用 和 手持 应 用 的 APK 都 有 相同 的 包 名 和 版 本 号 。 
3， 把 签 好 名 的 可 穿戴 应 用 放 到 手持 应 用 工程 的 res/raw 目录 下 。 我 们 假设 这 个 APK 名 
为 wearable app.apk ° 
4. 创建 res/xml/wearable app desc.xml 文件 ， 里 面包 含 可 穿戴 设备 的 版 本 信息 与 路 径 。 例 
如 : 
«wearableApp package="wearable.app.package.name"> 
<versionCode>1</versionCode> 
<versionName>1.0</versionName> 


<rawPathResId>wearable_app</rawPathResId> 
</wearableApp> 


package , versionCode 与 versionName 需要 和 可 穿戴 应 用 的 AndroidManifest.xml 里 面 的 
信息 一 致 。 rawPathResId 是 一 个 静态 变量 表示 APK 的 名 称 。 例 如 ， 对 
T wearable app.apk * 这 个 静态 变量 名 为 wearable app ° 
5. 添加 meta-data 标签 到 我 们 的 手持 应 用 的 «application» 4&4 F > 4& 917] 
用 wearable app desc.xml 文件 


<meta-data android:name-"com.google.android.wearable.beta.app" 
android: resource="@xml/wearable_app_desc"/> 


6. 构建 并 签名 手持 应 用 。 


2 ~ NE S x 

关闭 资产 压缩 

许多 构建 工具 会 自动 压缩 放 在 res/raw 目录 下 的 文件 。 因 为 可 穿戴 APK 已 经 被 压缩 过 了 ， 所 
以 这 些 工具 再 次 压缩 可 穿戴 APK 会 导致 可 穿戴 应 用 安装 程序 无 法 读 取 可 穿戴 应 用 。 


这 样 的 话 ， 安 装 失败 。 在 手持 应 用 上 ， Packageupdateservice 会 输出 如 下 的 错误 日 志 : "this 
file cannot be opened as a file descriptor; it is probably compressed." 


Android Studio 默认 不 会 压缩 APK， 但 是 如 果 我 们 使 用 其 它 构建 方式 ， 需 要 确保 不 要 重复 压缩 
可 穿戴 应 用 。 


通过 蓝牙 进行 调试 


编写 : kesenhoo - 原文 : http://developer.android.com/training/wearables/apps/bt- 
debugging.html 


我 们 可 以 通过 蓝牙 来 调试 我 们 的 可 穿戴 应 用 。 即 通过 蓝牙 把 调试 数据 输出 到 已 经 连接 了 开发 
电脑 的 手持 设备 上 。 


STL SRW 


1， 开 尼 手 持 设备 的 USB 调 试 : 
o 打开 设置 应 用 并 滑动 到 底部 。 
o 如 果 在 设置 里 面 没有 开发 者 选项 ， 点 击 关 于 手机 (或 者 关于 平板 ) ， 背 动 到 底部 ， 
点 击 build number 7 次 。 
o 返回 并 点 击 开 发 者 选项 
o 开局 USB 调 试 。 
2， 开启 可 穿戴 设备 的 蓝牙 调试 : 
o 点 击 主 界面 2 次 ， 来 到 Wear 菜 单 界面 。 
o 滑动 到 底部 ， 点 击 设置 。 
滑动 到 底部 ， 如 果 没 有 开发 者 选项 ， 点 击 关 于 ， 然 后 点 击 Build Number 7 次 。 
点 击 开发 者 选项 。 
o 开启 蓝牙 调试 。 


o 


o 


建立 调试 会 话 


1. 在 手持 设备 上 上， 打开 Android wear 配套 应 用 。 

2. 点 击 右上 角 的 菜单 ， 选 择 设置 。 

3. 开局 蓝牙 调试 。 我 们 将 会 在 选项 下 面 看 到 一 个 小 的 状态 信息 : 
Host: disconnected 


Target: connected 


4. 通过 USB 连 接手 持 设备 到 电脑 上 ， 并 执行 下 面 的 命令 


adb forward tcp:4444 localabstract:/adb-hub 
adb connect localhost:4444 


Note: 我 们 可 以 使 用 任何 可 用 的 端口 


在 android wear 配套 应 用 上 ， 我 们 将 会 看 到 状态 变 为 : 


Host: connected 
Target: connected 


调研 应 用 


当 运 行 abd devices 的 命令 时 ， 我 们 的 可 穿戴 设备 应 该 表示 为 localhost:4444。 执 行 任何 
的 adb 命令 ， 需 要 使 用 下 面 的 格式 : 


adb -s localhost:4444 «command» 


如 果 没 有 任何 其 他 的 设备 通过 TCP/IP 连 接 到 手持 设备 ( 即 模拟 器 ) ， 我 们 可 以 使 用 下 面 的 简 


短命 令 : 


adb -e «command» 


例如 : 


adb -e logcat 
adb -e shell 
adb -e bugreport 


为 可 穿戴 设备 创建 自 定义 UI 
编写 : roya 原文 :https://developer.android.com/training/wearables/ui/index.html 


可 穿戴 apps 的 用 户 界 面 明显 的 不 同 于 手持 设备 。 可 穿戴 设备 应 用 应 该 参考 Android Wear 设 计 
规范 和 实现 推荐 的 UI 模式 ， 这 些 保 证 在 为 可 穿戴 设备 优化 过 的 应 用 中 保持 统一 的 用 户 体 验 。 
这 个 课程 将 教 我 们 如 何 为 可 穿戴 应 用 创建 在 所 有 Android 可 穿戴 设备 上 看 上 去 都 不 错 的 自 定 义 
Ul 和 自 定义 的 notifications 。 为 了 达到 上 述 目的 ， 需 要 实现 这 些 UI 模式: 

e Card 


。 倒计时 和 确认 
e 长 按 退 出 


e 2D Picker 
e 多 选 List 
可 


穿戴 Ul 库 是 Android SDK 的 Google Repository 中 的 一 部 分 ， 其 中 提供 的 类 可 以 帮助 我 们 实 
现 这 些 模式 和 创建 工作 在 圆 形 和 方形 Android 可 穿戴 设备 的 layout。 


Note: 我 们 推荐 使 用 Android Studio 做 Android Wear 开 发 , 它 提供 工程 初始 配置 , 库 包 含 和 
方便 的 打包 ,这 些 在 ADT 中 是 没有 的 。 这 系列 教程 假定 你 正在 使 用 Android Studio ° 


Lessons 


定义 Layouts 

学 习 如 何 创建 在 圆 形 和 方形 Android Wear 设 备 上 看 起 来 不 错 的 layout 。 
创建 Card 

学 习 如 何 创 建 自 定义 layout 的 Card 

创建 List 

学 习 如 何 创建 为 可 穿戴 设备 优化 的 List 

创建 2D Picker 

学 习 如 何 实现 2D Picker UI 模式 以 导航 各 页 数据 

显示 确认 界面 

学 习 如 何在 用 户 完 成 操作 时 显示 确认 动画 


退出 全 屏 的 Activity 


学 习 如 何 实现 长 按 退 出 UI 模式 以 退出 全 屏 activities 


定义 Layouts 


编写 : roya Æ x-:https:;//developer.android.com/training/wearables/ui/layouts.html 
可 穿戴 设备 使 用 与 手持 Android 设 备 同样 的 布局 技术 ， 但 需要 有 具体 的 约束 来 设计 。 不 要 以 一 
个 手持 app 的 角度 开发 功能 和 UI 并 期 待 得 到 一 个 好 的 体验 。 关 于 如 何 设 计 优秀 的 可 穿戴 应 用 的 
更 多 信息 ， 请 阅读 Android Wear Design Guidelines。 
当 为 Android Wear 应 用 创建 layout 时 ， 我 们 需要 同时 考虑 方形 和 圆 形 屏幕 的 设备 。 在 圆 形 
Android Wear 设 备 上 所 有 放置 在 靠近 屏幕 边 角 的 内 容 可 能 会 被 剪裁 掉 ， 所 以 为 方形 屏幕 设计 
的 layouts 在 圆 形 设备 上 不 能 很 好 地 显示 出 来 。 对 这 类 问题 的 示范 请 查看 这 个 视频 Full Screen 


Apps for Android Wear ° 
举 个 例子 ，figure 1 展示 了 下 面 的 layout 在 圆 形 和 方形 屏幕 上 的 效果 : 


dre World! 


Hello Square World! 





Figure 1. 为 方形 屏幕 设计 的 layouts 在 圆 形 设备 上 不 能 很 好 显示 的 示范 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
xmlns: tools="http://schemas.android.com/tools" 
android: layout_width="match_parent" 
android: layout_height="match_parent" 
android: orientation="vertical"> 


<TextView 
android: id="@+id/text" 
android: layout_width="wrap_content" 
android: layout_height="wrap_content" 
android: text="@string/hello_square" /> 


</LinearLayout> 


上 述 范 例 的 文本 没有 正确 地 显示 在 圆 形 屏幕 上 。 
Wearable Ul| 库 为 这 个 问题 提供 了 两 种 不 同 的 解决 方案 : 


© 为 圆 形 和 方形 屏幕 定义 不 同 的 layouts。 我 们 的 app 会 在 运行 时 检查 设备 屏幕 形状 并 inflate 
正确 的 layout。 


e 用 一 个 包含 在 库 里 面 的 特殊 layout 同 时 适 配 方形 和 圆 形 设备 。 这 个 layout 会 在 不 同形 状 的 
设备 屏幕 窗口 中 插入 不 同 的 间隔 。 


当 我 们 希望 应 用 在 不 同形 状 的 屏幕 上 看 起 来 不 同时 ， oie: 。 当 我 们 希望 用 
一 个 相似 的 layout 在 两 种 屏幕 上 且 在 圆 形 屏幕 上 没有 视图 被 边缘 剪裁 时 ， 可 以 使 用 第 二 种 方 
案 o 


添加 Wearable UL £ 


当 我 们 使 用 Android Studio 的 工程 向 导 时 ，Android Studio 会 自动 地 在 wear 模块 中 包 
Wearable UI 库 。 为 了 在 工程 中 编译 到 这 个 库 ， 确 保 Extras > Google Repository 包 
装 在 Android SDK manager 里 ， 下 面 的 依赖 被 包含 在 wear 模块 的 build.gradle 文件 中 : 


dependencies { 
compile fileTree(dir: 'libs', include: ['*.jar']) 
compile 'com.google.android.support:wearable:-' 
compile 'com.google.android.gms:play-services-wearable:+' 


要 实现 以 下 的 布局 方法 需要 用 到 'com.google.android.support:wearable' 依赖 。 


ix X, API reference documentation 查 看 Wearable UL# 49 % o 


为 方形 和 圆 形 屏幕 指定 不 同 的 Layouts 


包含 在 Wearable Ul 库 中 的 watchviewstub 类 允许 我 们 为 方形 和 圆 形 屏幕 指定 不 同 的 layout。 这 
个 类 会 在 运行 时 检查 屏幕 形状 并 inflate 相 应 的 layout ° 
为 了 在 我 们 的 应 用 中 使 用 这 个 类 以 应 对 不 同 的 屏幕 形状 ， 我 们 需要 : 


e 添加 watchviewstub 作为 activity 的 layout 的 主 元 素 。 
e 使 用 rectLayout 属性 为 方形 屏幕 指定 一 个 layout 文 件 。 
e 使 用 roundLayout 属性 为 圆 形 屏幕 指定 一 个 layout 文 件 。 


类 似 下 面 定 义 activity 的 layout : 


«android.support.wearable.view.WatchViewStub 
xmlins:android-"http://schemas.android.com/apk/res/android" 
xmlins:app-"http://schemas.android.com/apk/res-auto" 
xmlns: tools="http://schemas.android.com/tools" 
android: id="@+id/watch_view_stub" 
android: layout_width="match_parent" 
android:layout height-"match parent" 
app:rectLayout-"Qlayout/rect activity wear" 
app:roundLayout-"Qlayout/round activity wear" 

«/android.support.wearable.view.WatchViewStub» 


Æ activity ¥ inflateix 4-layout : 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity wear); 


然后 为 方形 和 圆 形 屏幕 创建 不 同 的 layout 文 件 ， 在 这 个 例子 中 ， 我 们 需要 创 

建 res/layout/rect activity wear.xml 和 res/layout/round activity _ wear .Xml 两 个 文件 。 像 创 
建 手 持 应 用 的 layouts 一 样 定 义 这 些 layouts， 但 需要 考虑 可 穿戴 设备 的 限制 。 系 统 会 在 运行 时 
根据 屏幕 形状 来 inflate 适 合 的 layout 。 


取得 layout views 


我 们 为 方形 或 圆 形 屏幕 定义 的 layouts 在 watchviewstub 检测 到 屏幕 形状 之 前 不 会 被 inflate， 所 
以 你 的 app 不 能 立即 取得 它们 的 view。 为 了 取得 这 些 view， 需 要 在 我 们 的 activity 中 设置 一 人 
listener ， 当 屏幕 适 配 的 layout 被 inflate 时 会 通知 这 个 listener : 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity wear); 


WatchViewStub stub - (WatchViewStub) findViewById(R.id.watch view stub); 
stub.setOnLayoutInflatedListener(new WatchViewStub.OnLayoutInflatedListener() { 
@Override public void onLayoutinflated(WatchViewStub stub) { 
// Now you can access your views 
TextView tv = (TextView) stub. findViewById(R.id.text); 


3); 


E LLa youts 


使 用 感知 形状 的 Layout 


包含 在 Wearable Ul| 库 中 的 BoxInsetLayout 类 继承 自 FrameLayout， 该 类 允许 我 们 定义 一 个 同 
de od 这 个 类 适用 于 需要 根据 屏幕 形状 插入 间隔 的 情况 ， 并 让 我 们 
容易 地 将 view 对 其 到 屏幕 的 边缘 或 中 心 。 


Hello Round World! 





Figure 2. 在 圆 形 屏幕 上 的 窗口 间隔 


figure 2 中 灰色 的 部 分 显示 了 在 应 用 了 窗口 间隔 之 后 BoxinsetLayout 自动 将 它 的 子 view 放 置 
在 圆 形 屏幕 的 区 域 。 为 了 显示 在 这 个 区 域内 ， 子 View 需要 用 下 面 这 些 值 指定 layout_pox & 
性 : 


e 一 个 top ^ bottom ^ left 和 right 的 组 合 。 比 如 ， "jeft|top" 4Tviews «Fe kik 
缘 定 位 在 figure 2 的 灰色 区 域 里 面 。 
e all 将 所 有 子 view 的 内 容 定位 在 figure 2 的 灰色 区 域 里 面 。 


在 方形 屏幕 上 ， 窗 口 间 隔 为 0 layout box 属性 会 被 忽略 。 


Æ 3LLayouts 





Figure 3. 同一 个 layout 工 作 在 方形 和 圆 形 屏幕 上 


在 figure 3 中 展示 的 layout 使 用 了 BoxInsetLayout 


-N 
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， 该 layout 在 圆 形 和 方形 屏幕 上 都 可 以 使 用 : 


(<e) 


«android.support.wearable.view.BoxInsetLayout 
xmlins:android-"http://schemas.android.com/apk/res/android" 
xmlins:app-"http://schemas.android.com/apk/res-auto" 
android:background-"Qdrawable/robot background" 
android:layout height-"match parent" 
android: layout_width="match_parent" 
android: padding="15dp"> 


<FrameLayout 
android: layout_width="match_parent" 
android: layout_height="match_parent" 
android: padding="5dp" 
app: layout_box="all"> 


<TextView 
android: gravity="center" 
android:layout height-"wrap content" 
android: layout_width="match_parent" 
android: text="@string/sometext" 
android: textColor="@color/black" /> 


<ImageButton 
android: background="@null1" 
android: layout_gravity="bottom|left" 
android: layout_height="50dp" 
android: layout_width="50dp" 
android:src="@drawable/ok" /> 


<ImageButton 
android: background="@null" 
android: layout_gravity="bottom| right" 
android: layout_height="50dp" 
android: layout_width="50dp" 
android:src="@drawable/cancel" /> 
</FrameLayout> 
</android.support.wearable.view.BoxInsetLayout> 


注意 layout 中 的 这 些 部 分 : 


e android:padding="15dp" 


这 行 指定 了 BoxInsetLayout 元 素 的 padding。 因 为 在 圆 形 设备 上 窗口 间隔 大 于 15dp， 所 以 这 
个 padding 只 应 用 在 方形 屏幕 上 。 


èe  android:padding-"5dp" 


这 行 指定 内 部 FrameLayout 元 素 的 padding。 这 个 padding 同 时 应 用 在 方形 和 圆 形 屏幕 上 。 在 
方形 屏幕 上 ， 按 钮 和 窗口 间隔 总 的 padding 是 20dp(15+5)， 在 圆 形 屏 幕 上 是 5dp。 


*  app:layout box-"all" 


这 行 声明 FrameLayout 和 它 的 子 views 都 被 放 在 圆 形 屏幕 上 窗 口 间 隔 定 义 的 区 域 里 。 这 行 在 方 
形 屏幕 上 没有 任何 效果 。 


创建 Card 


编写 : roya 原文 :https://developer.android.com/training/wearables/ui/cards.html 


Card 在 不 同 的 应 用 上 以 一 致 的 外 观 为 用 户 显示 信息 。 这 个 章节 介绍 如 何在 Android Wear 应 用 
中 创建 Card ° 


Wearable Ul| 库 提供 了 为 穿戴 设备 特别 设计 的 Card 实 现 9 这 个 库 包含 了 cardFrame 类 ， 它 将 
view 包 在 一 个 Card 风 格 的 框架 中 该 框架 有 和 白 e qx b E A fe 26,444 IH * ° CardFrame 只 
能 包含 一 个 直接 子 类 ， 通 常 是 一 个 layout 管 理 器 ， 我 们 可 以 向 它 添加 其 他 views 以 定制 Card 内 


o 


wy B 


你 有 两 种 方法 向 应 用 添加 Card : 


e 使 用 或 继承 CardFragment Ko 
e 在 layout 的 cardscrollview 中 添加 一 个 Card ° 


一 -一 


Note: 这 个 课程 展示 了 如 何在 Android Wear activities 中 添加 Card。Android 可 穿戴 设备 上 
的 notifications 同 样 以 Card 的 形式 显示 。 更 多 信息 请 查看 为 Notification 赋 加 可 穿戴 特性 。 


创建 Card Fragment 


cardFragment 类 提供 一 个 默认 的 Card layout， 该 layout 含 有 一 个 标题 、 描 述 文字 和 一 个 图 
标 。 如 果 figure 1 的 默认 Card layout 符 合 你 的 要 求 ， 那 么 使 用 这 个 方法 向 你 的 app 添 加 Card。 


| Description 








Figure 1. 默认 的 cardFragment layout. 


为 了 添加 一 个 cardFragment 到 应 用 中 ， 我 们 需要 : 


e 在 layout 中 ， 为 包含 Card 的 节点 分 配 一 个 ID 
e 在 activity 中 ， 创 建 一 个 cardFragment 实例 
e 使 用 fragment 管 理 器 将 cardFragment 实例 添加 到 它 的 容器 


下 面 的 示例 代码 显示 了 Figure 1 中 的 屏幕 显示 代码 : 


«android.support.wearable.view.BoxInsetLayout 
xmlns:android-"http://schemas.android.com/apk/res/android" 
xmlns:app-z"http://schemas.android.com/apk/res-auto" 
android:background-"Qdrawable/robot background" 

android: layout_height="match_parent" 

android: layout_width="match_parent"> 


<FrameLayout 
android: id="@t+id/frame_layout" 
android: layout_width="match_parent" 
android:layout height-"match parent" 
app: layout_box="bottom"> 


</FrameLayout> 
</android.support.wearable.view.BoxInsetLayout> 


下 面 的 代码 添加 cardFragment 实例 到 Figure 1 activity? : 


protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity wear activity2); 


FragmentManager fragmentManager - getFragmentManager(); 

FragmentTransaction fragmentTransaction - fragmentManager.beginTransaction(); 

CardFragment cardFragment - CardFragment.create(getString(R.string.cftitle), 
getString(R.string.cfdesc), 
R.drawable.p); 

fragmentTransaction.add(R.id.frame layout, cardFragment); 

fragmentTransaction.commit(); 


为 了 使 用 CardFragment 创建 一 个 带 有 自 定义 layout 的 Card ， 需要 继承 这 个 类 和 重 写 它 


的 onCreateContentView 方法 。 


Asta CardFrame =! Layout 


我 们 也 可 以 直接 添加 一 个 Card 到 layout 中 ， 如 figure 2/T 7% ° 4 Ar Zz A layout x # ¥ 4) Card B 
定义 一 个 layout 时 ， 使 用 这 个 方法 。 
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Define your layout 
inside a CardFrame. 
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Custom Card 


Define your layout inside 
| a CardFrame. 





Figure 2. 添加 一 个 cardFrame 到 |ayout. 


下 面 的 layout 代 码 例子 示范 了 一 个 含有 两 个 节点 的 垂直 linear layout。 你 可 以 创建 更 加 复杂 的 
layouts 以 适合 你 应 用 的 需要 。 


创建 Card 


«android.support.wearable.view.BoxInsetLayout 
xmlns:android-"http://schemas.android.com/apk/res/android" 
xmlns:app-"http://schemas.android.com/apk/res-auto" 
android:background-"Qdrawable/robot background" 
android:layout height-"match parent" 

android: layout_width="match_parent"> 


«android.support.wearable.view.CardScrollView 
android:id-"Q-id/card scroll view" 
android:layout height-"match parent" 
android: layout_width="match_parent" 
app: layout_box="bottom"> 


<android.support.wearable.view.CardFrame 
android:layout height-"wrap content" 
android: layout_width="fill_parent"> 


<LinearLayout 
android:layout height-"wrap content" 
android:layout width-"match parent" 
android:orientation="vertical" 
android: paddingLeft="5dp"> 
<TextView 
android: fontFamily="sans-serif-light" 
android:layout height-"wrap content" 
android:layout width-"match parent" 
android:text-"Qstring/custom card" 
android: textColor="@color/black" 
android: textSize="20sp"/> 
<TextView 
android: fontFamily="sans-serif-light" 
android:layout height-"wrap content" 
android: layout_width="match_parent" 
android: text="@string/description" 
android: textColor="@color/black" 
android: textSize="14sp"/> 
</LinearLayout> 
</android.support.wearable. view. CardFrame> 
</android. support .wearable. view. CardScrollView> 
</android.support.wearable.view.BoxInsetLayout> 


4 cardScrollview 的 内 容 小 于 容器 时 ， 这 个 例子 上 的 cardscrollview 节点 让 我 们 可 以 配置 
Card 的 gravity，。 这 个 例子 是 Card 对 齐 屏 幕 底部 : 


545 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
setContentView(R.layout.activity_wear_activity2); 


CardScrollView cardScrollView = 
(CardScrollView) findViewById(R.id.card scroll view); 
cardScrollView.setCardGravity(Gravity.BOTTOM); 


CardScrollview 检测 屏幕 形状 后 以 不 同 的 显示 方式 在 圆 形 或 方形 设备 上 显示 Card (在 圆 形 屏 
幕 上 使 用 更 宽 的 侧 边 缘 。 不 管 怎样 ， 在 BoxInsetLayout 中 放置 CardScrollView 节点 然后 使 
用 layout_box="bottom" 属性 ， 这 对 圆 形 屏幕 上 的 Card 对 齐 底部 并 且 没 有 内 容 被 剪裁 是 很 有 用 
的 。 


创建 List 


编写 : roya Æ X:https://developer.android.com/training/wearables/ui/lists.htm| 


List 让 用 户 在 可 穿戴 设备 上 很 容易 地 从 一 组 选项 中 选择 一 个 项 目 。 这 个 课程 介绍 了 如 何在 
Android Wear 应 用 中 创建 List ° 


Wearable Ul| 库 包含 了 wearableListview 类 ， 该 类 是 对 可 穿戴 设备 进行 优化 的 List 实 现 。 
Note: Android SDK 中 的 Notifications 例子 示范 了 如 何在 应 用 中 使 用 


WearableListView 。 这 个 例子 的 位 于 android-sdk/samples/android- 


20/wearable/Notifications 目录 。 
为 了 在 Android Wear 应 用 中 创建 List， 我 们 需要 : 


添加 wearableListview 元 素 到 activity 的 layout 定 义 中 。 
为 List 选 项 创建 一 个 自 定 义 的 layout 实 现 。 

使 用 这 个 实现 为 List 选 项 创建 一 个 layout 定 义 文件 。 
创建 一 个 adapter 以 填充 List ° 

指定 这 个 adapter 到 wearableListview 元 素 。 


mm ON 一 


下 面 的 章节 有 这 些 步骤 的 详细 描述 。 
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Figure 3: Æ Android Wear 上 的 List View. 


添加 List View 


下 面 的 layout 使 用 BoxInsetLayout 添加 了 一 个 List view 到 activity 中 ， 所 以 这 个 List 可 以 正确 地 
显示 在 圆 形 和 方形 两 种 设备 上 : 


«android.support.wearable.view.BoxInsetLayout 
xmlns:android="http://schemas.android.com/apk/res/android" 
xmLlns:app="http://schemas.android.com/apk/res-auto" 
android:background-"Qdrawable/robot background" 
android:layout height-"match parent" 
android: layout_width="match_parent"> 


<FrameLayout 
android: id="@t+id/frame_layout" 
android: layout_height="match_parent" 
android: layout_width="match_parent" 
app: layout_box="left|bottom|right"> 


«android.support.wearable.view.WearableListView 
android:id-"Q-id/wearable list" 
android:layout height-"match parent" 
android: layout_width="match_parent"> 

</android.support.wearable.view.WearableListView> 

</FrameLayout> 
</android.support.wearable.view.BoxInsetLayout> 


为 List 选 项 创建 一 个 Layou 实 现 


在 许多 例子 中 ， 每 个 List 选 项 都 由 一 个 图 标 和 一 个 描述 组 成 。Android SDK F 49 Notifications 
例子 实现 了 一 个 自 定义 layout : 继承 LinearLayout 以 合并 两 元 素 到 每 个 List 选 项 。 这 个 layout 也 
实现 了 wearableListView.OncenterproximityListener 接口 里 的 方法 ， 以 实现 在 用 户 在 List 中 滚 
动 时 ， WearablelistView 的 事件 而 改变 选项 图 标 闫 色 和 渐 隐 文字 : 


public class WearableListItemLayout extends LinearLayout 
implements WearableListView.OnCenterProximityListener { 


private ImageView mCircle; 
private TextView mName; 


private final float mFadedTextAlpha; 
private final int mFadedCircleColor; 
private final int mChosenCircleColor; 


public WearableListItemLayout(Context context) 1 
this(context, null); 


public WearableListItemLayout(Context context, AttributeSet attrs) { 
this(context, attrs, 0); 


public WearableListItemLayout(Context context, AttributeSet attrs, 
amtSdetSEydeyst 
super(context, attrs, defStyle); 


mFadedTextAlpha - getResources() 
.getInteger(R.integer.action text faded alpha) / 100f; 

mFadedCircleColor - getResources().getColor(R.color.grey); 

mChosenCircleColor - getResources().getColor(R.color.blue); 


// Get references to the icon and text in the item layout definition 
@Override 
protected void onFinishinflate() { 

super.onFinishInflate(); 

// These are defined in the layout file for list items 

// (see next section) 

mCircle - (ImageView) findViewById(R.id.circle); 

mName - (TextView) findViewById(R.id.name); 


@Override 
public void onCenterPosition(boolean animate) { 
mName.setAlpha(if); 
((GradientDrawable) mCircle.getDrawable()).setColor(mChosenCircleColor); 


@Override 

public void onNonCenterPosition(boolean animate) { 
((GradientDrawable) mCircle.getDrawable()).setColor(mFadedCircleColor); 
mName.setAlpha(mFadedTextAlpha); 


我 们 也 可 以 创建 animator 对 象 以 放大 List 中 间 选 项 的 图 标 。 我 们 可 以 使 


用 WearableListView.OnCenterProximityListener 接口 的 onCenterPosition() 和 


onNonCenterPosition() 回调 方法 来 管理 animator 对 象 。 更 多 关于 animator 对 象 的 信息 请 查 


看 Animating with ObjectAnimator 


A Items! 


在 为 List 选 项 实现 自 定 义 layout 之 后 ， 我 们 需要 提供 一 个 layout 解 释文 件 以 具体 说 明 list item P 
的 组 件 参 数 。 下 面 的 layout 使 用 先前 的 自 定义 layout 实 现 ， 并 且 定 义 图 标 和 文本 view， 这 两 个 


建 Layout 解 释 


View 的 ID 对 应 layout 实 现 类 的 ID : 


res/layout/list item.xml 


<com.example.android.support.wearable.notifications.WearableListItemLayout 
xmlns:android="http://schemas.android.com/apk/res/android" 


android:gravity-"center vertical" 


android: layout_width="match_parent" 
android: layout_height="80dp"> 


<ImageView 
android 
android 
android 
android 


<TextView 
android 
android 
android 
android 
android 
android 
android 


android: 
android: 


tid="@+tid/circle" 

:layout height-"20dp" 
:layout margin-"16dp" 
: Layout_width="20dp" 
android: 


src="@drawable/wl_circle"/> 


:idz"Q-«-id/name" 

:gravity-"center vertical|left" 

:layout width-"wrap content" 

:layout marginRight-"16dp" 

:layout height-"match parent" 
:fontFamily-"sans-serif-condensed-light" 
:LineSpacingExtra="-4sp" 


textColor="@color/text_color" 
textSize="16sp"/> 


</com.example.android.support.wearable.notifications.WearableListItemLayout> 
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Adapter H A 234 À wearableListview 。 下 面 的 adapter 基 于 strings 数 组 元 素 填充 了 List : 


private static final class Adapter extends WearableListView.Adapter { 


private String[] mDataset; 


private final Context mContext; 


private final LayoutInflater mInflater; 


建 List 


// Provide a suitable constructor (depends on the kind of dataset) 
public Adapter(Context context, String[] dataset) { 

mContext - context; 

mInflater - LayoutInflater.from(context); 

mDataset - dataset; 


// Provide a reference to the type of views you're using 
public static class ItemViewHolder extends WearableListView.ViewHolder { 
private TextView textView; 
public ItemViewHolder(View itemView) { 
super(itemView); 
// find the text view within the custom item's layout 
textView - (TextView) itemView.findViewById(R.id.name); 


// Create new views for list items 
// (invoked by the WearableListView's layout manager) 
@Override 
public WearableListView.ViewHolder onCreateViewHolder(ViewGroup parent, 
int viewType) { 
// Inflate our custom layout for list items 
return new ItemViewHolder(mInflater.inflate(R.layout.list_item, null)); 


// Replace the contents of a list item 
// Instead of creating new views, the list tries to recycle existing ones 
// (invoked by the WearableListView's layout manager ) 
@Override 
public void onBindViewHolder(WearableListView.ViewHolder holder, 
int position) { 
// retrieve the text view 
ItemViewHolder itemHolder - (ItemViewHolder) holder; 
TextView view - itemHolder.textView; 
// replace text contents 
view.setText(mDataset[position]); 
// replace list item's metadata 
holder.itemView.setTag(position); 


// Return the size of your dataset 
// (invoked by the WearableListView's layout manager) 
@Override 
public int getItemCount() { 
return mDataset.length; 


连接 Adapter 和 设置 Click Listener 


在 我 们 的 activity 中 ， 从 layout 中 取得 wearableListview 元 素 的 引用 ， 分 配 一 个 adapter 实 例 以 
填充 List， 然 后 设置 一 个 click listener 以 完成 当 用 户 选择 了 一 个 特定 的 List 选 项 的 动作 。 


public class WearActivity extends Activity 
implements WearableListView.ClickListener { 


// Sample dataset for the list 
Stringi elements = { Lrst item a", VErst Tem 2) y 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.my list activity); 


// Get the list component from the layout of the activity 
WearableListView listView = 
(WearableListView) findViewById(R.id.wearable_list); 


// Assign an adapter to the list 
listView.setAdapter(new Adapter(this, elements)); 


// Set a click listener 
listView.setClickListener(this); 


// WearableListView click listener 

@Override 

public void onClick(WearableListView.ViewHolder v) { 
Integer tag = (Integer) v.itemView.getTag(); 
// use this data to complete some action 


@Override 
public void onTopEmptyRegionClick() { 
} 


创建 2D Picker 


编写 : roya Æ X:https://developer.android.com/training/wearables/ui/2d-picker.html 


Android Wear 中 的 2D Picker 模 式 允许 用 户 像 换 页 一 样 从 一 组 选项 中 导航 和 选择 。Wearable 
Ul 库 让 我 们 可 以 容易 地 用 一 个 page grid 来 实现 这 个 模式 。 其 中 ，page grid 是 一 个 layout 管 理 
器 ， 它 允许 用 户 重 直 和 水 平 滚动 页 面 。 


要 实现 这 个 模式 ， 我 们 需要 添加 一 个 GridviewPager 元 素 到 activity 的 layout 中 ， 然 后 实现 一 个 
继承 FragmentGridPagerAdapter 类 的 adapter 以 提供 一 组 页 面 。 


Note: Android SDK 中 的 GridqViewPager 例 子 示范 了 如 何在 应 用 中 使 用 GridviewPager 
layout 。 这 个 例子 的 位 于 android-sdk/samples/android-20/wearable/GridViewPager 目录 


中 。 


洒 加 Page Grid 
像 下 面 一 样 添加 一 个 GridviewPager 元 素 到 layout 描 述 文件 : 


«android.support.wearable.view.GridViewPager 
xmlns:android="http://schemas.android.com/apk/res/android" 
android: id="@+id/pager" 
android: layout_width="match_parent" 
android:layout height-"match parent" /> 


我 们 可 以 使 用 任何 定义 Layouts 技 术 以 保证 2D picker 可 以 工作 在 圆 形 和 方形 两 种 设备 上 。 


Ky 

实现 Page Adapter 

Page Adapter 提 供 一 组 页 面 以 填充 GridviewPager 部 件 。 要 实现 这 个 adapter， 需 要 继承 
Wearable Ul ¥ 4) FragmentGridPageAdapter 类 。 


举 个 例子 ，Android SDK 内 的 GridqViewPager 例 子 中 包含 了 下 面 的 adapter 实 现 ， 该 实现 提供 一 
组 静态 的 具有 自 定 义 背 景 图 片 的 card : 





public class SampleGridPagerAdapter extends FragmentGridPagerAdapter { 
private final Context mContext; 


public SampleGridPagerAdapter(Context ctx, FragmentManager fm) { 
super(fm); 
mContext - ctx; 


static final int[] BG IMAGES - new int[] 1 
R.drawable.debug background 1, 
R.drawable.debug background 5 

}; 


// A simple container for static data in each page 
private static class Page { 

// static resources 

int titleRes; 

int textRes; 

int iconRes; 


// Create a static set of pages in a 2D array 
private final Page[][] PAGES = { ... }; 


// Override methods in FragmentGridPagerAdapter 


picker 调 用 getFragment 和 getBackground 来 取得 内 容 以 显示 到 grid 的 每 个 位 置 中 。 


554 


// Obtain the UI fragment at the specified position 
@Override 
public Fragment getFragment(int row, int col) { 
Page page - PAGES[row][col]; 
String title - 
page.titleRes !- 0 ? mContext.getString(page.titleRes) : null; 
String text - 
page.textRes !- 0 ? mContext.getString(page.textRes) : null; 
CardFragment fragment - CardFragment.create(title, text, page.iconRes); 


// Advanced settings (card gravity, card expansion/scrolling) 
fragment.setCardGravity(page.cardGravity); 
fragment.setExpansionEnabled(page.expansionEnabled); 
fragment.setExpansionDirection(page.expansionDirection); 
fragment.setExpansionFactor(page.expansionFactor); 

return fragment; 


// Obtain the background image for the page at the specified position 
@Override 
public ImageReference getBackground(int row, int column) { 

return ImageReference.forDrawable(BG IMAGES[row % BG IMAGES.length]); 


getRowCount 方法 告诉 picker 有 多 少 行内 容 是 可 获得 的 ， getcolumncount 方法 告诉 picker 每 行 
中 有 多 少 列 内 容 是 可 获得 的 。 


// Obtain the number of pages (vertical) 
@Override 
public int getRowCount() { 

return PAGES. length; 


// Obtain the number of pages (horizontal) 

@Override 

public int getColumnCount(int rowNum) { 
return PAGES[rowNum]. length; 


adapter 有 是 实现 细节 取决 于 我 们 指定 的 某 组 页 面 。 由 adapter 提 供 的 每 个 页 面 是 Fragement 类 
型 。 在 这 个 例子 中 ， 每 个 页 面 是 一 个 使 用 默认 card layouts? cardFragment 实例 。 然 而 ， 我 们 
可 以 在 同一 个 2D picker 混 合 不 同类 型 的 页 面 ， 比 如 cards，action icons， 和 自 定义 layouts， 
由 具体 情况 决定 。 


不 是 所 有 行 都 需要 有 同样 数量 的 页 面 。 注 意 这 个 例子 中 的 每 行 有 不 同 的 列 数 。 我 们 也 可 以 用 
一 个 GridviewPager 组 件 实现 只 有 一 行 或 一 列 的 1D picker ° 


Each page Is 


created using a 
CardFragment. A 
layout Is placed 
inside the card and 





Figure 1: GridViewPager 例 子 


对 于 那些 超出 设备 屏幕 大 小 的 card ， GridViewPager 为 它们 提供 了 滚动 支持 。 这 个 例子 配置 了 
每 张 card 可 以 按照 需要 进行 展开 ， 所 以 用 户 可 以 滚动 卡片 的 内 容 。 当 用 户 滚动 到 card 的 尽头 ， 
向 同一 方向 滑动 将 显示 grid 中 的 下 一 页 (如 果 下 一 页 存在 的 话 ) © 


我 们 可 以 使 用 getBackground() 方法 自 定 义 每 页 的 背景 。 当 用 户 在 页 面 间 滑动 
时 ， GridViewPager 自动 在 不 同 的 背景 之 问 使 用 视差 滚动 和 淡出 效果 。 

分 配 adapter 实 例 给 page grid 

在 activity 中 ， 分 配 一 个 adapter 实 现实 例 给 GridviewPager 组 件 : 


public class MainActivity extends Activity { 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
setContentView(R.layout.activity main); 


final GridViewPager pager - (GridViewPager) findViewById(R.id.pager); 
pager.setAdapter(new SampleGridPagerAdapter(this, getFragmentManager())); 


显示 确认 界面 


编写 : roya 原文 :https://developer.android.com/training/wearables/ui/confirm.html 


Android Wear 应 用 中 的 确认 界面 (Confirmations) 通 常 是 全 屏 或 者 相 比 于 手持 应 用 占 更 大 的 部 
分 。 这 样 确保 用 户 可 以 一 眼看 到 确认 界面 (confirmations) 且 有 一 个 足够 大 的 触摸 区 域 用 于 取消 
一 个 操作 。 


Wearable UI 库 帮助 我 们 在 Android Wear 应 用 中 显示 确认 动画 和 定时 器 : 

确认 定时 器 

© 自动 确认 定时 器 为 用 户 显 示 一 个 定时 器 动画 ， 让 用 户 可 以 取消 他 们 最 近 的 操作 。 
确认 界面 动画 

。 确认 界面 动画 给 用 户 在 完成 一 个 操作 时 的 视觉 反馈 。 


下 面 的 章节 将 演示 了 如 何 实现 这 些 模 式 。 


使 用 自动 确认 定时 咒 


自动 确认 定时 器 让 用 户 取消 刚 做 的 操作 。 当 用 户 做 一 个 操作 ， 我 们 的 应 用 会 显示 一 个 带 有 定 
时 动画 的 取消 按钮 ， 并 且 启 动 该 定时 器 。 用 户 可 以 在 定时 结束 前 选择 取消 操作 。 如 果 用 户 选 
择 取 消 操作 或 定时 结束 ， 我 们 的 应 用 会 得 到 一 个 通知 。 


| made a reservation 
at /:30 pm 





Figure 1: 一 个 确认 定时 器 . 


为 了 在 用 户 完成 操作 时 显示 一 个 确认 定时 器 : 


1. 添加 DelayedConfirmationview 元 素 到 layout 中 。 


2. 在 activity 中 实现 DelayedconfirmationListener 接口 。 
3. 当 用 户 完 成 一 个 操作 时 ， 设 置 定时 器 的 定时 时 间 然 后 启动 它 。 


像 下 面 这 样 添加 DelayedConfirmationview 元 素 到 layout 中 : 


<and 


«/an 


在 layo 


roid.support.wearable.view.DelayedConfirmationView 
android: id="@+id/delayed_confirm" 

android: layout_width="40dp" 

android: layout_height="40dp" 

android: src="@drawable/cancel_circle" 
app:circle_border_color="@color/lightblue" 
app:circle_border_width="4dp" 
app:circle_radius="16dp"> 
droid.support.wearable.view.DelayedConfirmationView> 


ut 定义 中 ， 我 们 可 以 用 android:src 制定 一 个 drawable 资 源 ， 用 于 显示 在 圆 形 里 。 然 后 


直接 设置 圆 的 参数 。 


为 了 获得 定时 结束 或 用 户 点 击 按钮 时 的 通知 ， 需 要 在 activity 中 实现 相应 的 listener 方 法 : 


publ 


ic class WearActivity extends Activity implements 
DelayedConfirmationView.DelayedConfirmationListener { 


private DelayedConfirmationView mDelayedView; 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState) ; 
setContentView(R.layout.activity wear activity); 


mDelayedView - 
(DelayedConfirmationView) findViewById(R.id.delayed confirm); 
mDelayedView.setListener(this); 


@Override 
public void onTimerFinished(View view) { 
// User didn't cancel, perform the action 


@Override 
public void onTimerSelected(View view) { 
// User canceled, abort the action 


动 定 时 器 ， 添 加 下 面 的 代码 到 activity 处 理 用 户 选择 茶 个 操作 的 位 置 中 : 


mDelayedView.setTotalTimeMs(2000); 


mDelayedView.start(); 


显示 确认 动画 


为 了 当 用 户 在 我 们 的 应 用 中 完成 一 个 操作 时 显示 确认 动画 ， 我 们 需要 创建 一 个 从 应 用 中 的 某 
个 activity 启 动 confirmationactivity 的 intent。 我 们 可 以 用 EXTRA_ANIMATION_TYPE intent extra 
来 指定 下 面 其 中 一 种 动画 : 


@ SUCCESS_ANIMATION 
9 FAILURE ANIMATION 


@ OPEN ON PHONE ANIMATION 


我 们 还 可 以 在 确认 图 标 下 面 添加 一 条 消息 。 


Message Sent 





Figure 2: 一 个 确认 动画 


要 在 应 用 中 使 用 confirmationactivity ， 首 先 在 manifest 文 件 声明 这 个 activity : 


«manifest» 
«application» 


«activity 
android:name="android.support.wearable.activity.ConfirmationActivity"> 
</activity> 
</application> 
</manifest> 


然后 确定 用 户 操作 的 结果 ， 并 使 用 intent 启 动 activity: 


Intent intent = new Intent(this, ConfirmationActivity.class); 
intent.putExtra(ConfirmationActivity.EXTRA ANIMATION TYPE, 
ConfirmationActivity.SUCCESS ANIMATION); 
intent.putExtra(ConfirmationActivity.EXTRA MESSAGE, 
getString(R.string.msg sent)); 
startActivity(intent); 


当 确 认 动 画 显 示 结 束 后 ， Confirmationactivity 会 销毁 (Finish) ， 我 们 的 的 activity 会 恢复 


(Resume) 。 


iE E SJ Activity 


编写 : roya Æ x-:https:;//developer.android.com/training/wearables/ui/exit.html 
默认 情况 下 ， 用 户 通过 从 左 到 右 滑动 退出 Android Wear activities。 如 果 应 用 含有 水 平 滚动 的 
内 容 ， 用 户 首先 滑动 到 内 容 边 缘 ， 然 后 再 次 从 左 到 右 滑动 即 退出 app。 
对 于 更 加 沉浸 式 的 体验 ， 比 如 在 应 用 中 可 以 任意 方向 地 滚动 地 图 ， 这 时 我 们 可 以 在 应 用 中 从 
用 滑动 退出 手势 。 然 而 ， 如 果 我 们 禁用 了 这 个 功能 ， 那 么 我 们 必须 使 用 Wearable UIE F 


x 人 X TORRE OME USES 用 。 当 然 ， 我 们 需要 在 用 户 第 一 
行 我 们 应 用 的 时 候 提醒 用 户 可 以 通过 长 按 退 出 应 用 。 


更 多 关于 退出 Android Wear activities 的 设计 指南 ， 请 查看 Breaking out of the card » 


禁用 滑动 退出 手 劳 


如 果 我 们 应 用 的 用 户 交 互 模型 与 滑动 退出 手势 相 冲 突 ， 那 么 我 们 可 以 在 应 用 中 禁用 它 。 为 了 
禁用 滑动 退出 手势 ， 需 要 继承 默认 的 theme， 然 后 设置 android:windowswipeToDismiss 属性 


为 false : 


«style name-"AppTheme" parent="Theme.DeviceDefault"> 
«item name="android:windowSwipeToDismiss">false</item> 
«/style» 


如 果 我 们 禁用 了 这 个 手势 ， 那 么 我 们 需要 实现 长 按 退 出 UI 模型 来 让 用 户 退 出 我 们 的 应 用 ， 下 
面 的 章节 会 介绍 相关 内 容 。 


实现 长 按 退 出 模式 


要 在 activity 中 使 用 pissmissoverlayview 类 ， 添 加 下 面 这 个 节点 到 layout 文 件 ， 让 它 全 屏 且 禾 
盖 在 所 有 其 他 view 上 “。 例 如 : 


<FrameLayout 
xmlins:android-"http://schemas.android.com/apk/res/android" 
android:layout height-"match parent" 
android: layout_width="match_parent"> 


<!-- other views go here --> 


<android.support.wearable.view.DismissOverlayView 
android:id-"Q*id/dismiss overlay" 
android:layout height-"match parent" 
android: layout_width="match_parent"/> 
<FrameLayout> 


在 我 们 的 activity 中 ， 取 得 DismissoverlayView 元 素 并 设置 一 些 提 示 文 字 。 这 些 文字 会 在 用 户 
第 一 次 运行 我 们 的 应 用 时 提醒 用 户 可 以 使 用 长 按 手 势 退 出 应 用 。 接 着 用 GestureDetector 检测 
长 按 动作 : 


public class WearActivity extends Activity { 


private DismissOverlayView mDismissOverlay; 
private GestureDetector mDetector; 


public void onCreate(Bundle savedState) { 
super.onCreate(savedState); 
setContentView(R.layout.wear activity); 


// Obtain the DismissOverlayView element 

mDismissOverlay - (DismissOverlayView) findViewById(R.id.dismiss overlay); 
mDismissOverlay.setIntroText(R.string.long press intro); 
mDismissOverlay.showIntroIfNecessary(); 


// Configure a gesture detector 
mDetector = new GestureDetector(this, new SimpleOnGestureListener() { 
public void onLongPress(MotionEvent ev) { 
mDismissOverlay.show(); 


j 

35 
} 
// Capture long presses 
@Override 
public boolean onTouchEvent(MotionEvent ev) { 

return mDetector.onTouchEvent(ev) || super.onTouchEvent(ev); 
} 


当 系 统 检测 到 一 个 长 按 动作 ， Dismissoverlayview 会 显示 一 个 退出 按钮 。 如 果 用 户 点 击 它 ， 
那么 我 们 的 activity 会 被 终止 。 


退出 全 屏 的 Activity 
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发 送 并 同步 数据 


^h 5 :wly2014 - /$ X: http://developer.android.com/training/wearables/data- 
layer/index.html 


可 穿戴 数据 层 API(The Wearable Data Layer API) * Google Play services 的 一 部 分 ， 为 手持 
与 可 穿戴 应 用 提供 了 一 个 交流 通道 。 此 API 包 括 一 系列 的 数据 对 象 ， 其 可 由 系统 通过 网 络 和 能 
告知 应 用 数据 层 重 要 事件 的 监听 器 发 送 并 同步 : 


Data ltems 
Dataltem 提 供 了 手持 设备 与 可 穿戴 设备 间 的 自动 同步 的 数据 储存 。 
Messages 


MessageApi 类 可 以 发 送 消 息 和 善于 处 理 远 程 过 程 调 用 协议 (RPC) ， 比 如 ， 从 可 穿戴 设备 上 
控制 手持 设备 的 媒体 播放 器 ， 或 在 可 穿戴 设备 上 启动 一 个 来 自 手持 设备 的 intent。 消 息 还 适合 
单 向 请 求 或 者 请 求 /响应 通信 模型 。 如 果 手 持 设备 与 可 穿戴 设备 成 功 连接 ， 那 么 系统 会 将 传递 

的 消息 放 进 队列 并 返回 一 个 成 功 的 结果 码 。 和 否则， 会 返回 一 个 错误 。 成 功 码 并 不 代表 成 功 地 

传递 消息 ， 这 是 因为 设备 可 能 在 收 到 结果 码 之 后 断 开 连接 。 


Asset 


Asset 对 象 用 于 发 送 如 图 像 这 样 的 二 进 制 数据 。 将 资源 附加 到 数据 元 ， 系 统 会 自动 负责 传递 ， 
并 通过 缓存 大 的 资源 来 避免 重复 传送 以 保护 蓝牙 带宽 。 


WearableListenerService (for services) 


拓展 的 WearableListenerService 能 够 监听 一 个 service 中 重要 的 数据 层 事件 。 系 统 控制 
WearableListenerService 的 生命 周期 ， 并 当 需 要 发 送 数据 元 或 消息 时 ， 将 其 与 service 绑 定 ， 
Xs Wl AME o 


DataListener (for foreground activities) 


在 一 个 前 台 activity 中 实现 DataListener 能 够 监听 重要 的 数据 通道 事件 。 只 有 当 用 户 频繁 地 使 用 
应 用 时 ， 用 此 代替 WearableListenerService 来 监听 事件 变化 。 


Channel 


使 用 ChannelApi 类 来 从 手持 设备 传输 大 的 数据 项 到 可 穿戴 设备 ， 例 如 音乐 和 电影 。Channel 
API 用 于 传输 数据 有 如 下 的 好 处 : 


e 当 使 用 Asset 对 象 附加 于 Dataltem 对 象 时 ， 在 两 个 或 两 个 以 上 已 连接 的 设备 间 传 输 大 的 数 
据 文 件 是 不 会 自动 同步 。 不 像 DataApi，Channel API 节省 磁盘 空间 ， 而 DataApi 类 是 在 
同步 已 连接 设备 之 前 ， 就 在 本 地 设备 上 创建 一 份 资源 的 拷贝 。 


e 可 竺 地 传输 对 于 使 用 MessageApi 类 太 大 的 文件 。 
e 传输 数据 流 ， 例 如 从 网 络 服务 器 下 载 的 音乐 或 者 从 麦克 风 传 进来 的 声音 。 


Warning: SR 为 手持 设备 与 可 穿戴 设备 间 通 信 设 计 ， 所 以 我 们 只 能 使 用 
Api 来 建立 这 些 设备 间 的 通信 。 例 如 ， 不 能 试 着 打开 底层 sockets 来 创建 通信 通道 。 


Android Wear 支 持 多 个 可 穿戴 设备 连接 到 一 个 手持 式 设备 。 例 如 ， 当 用 于 在 手持 设备 上 保存 

了 一 个 笔记 ， 它 会 自动 出 现在 用 户 的 Wear 设 备 上 。 为 了 在 设备 之 间 同 步 数 据 ，Google 的 服务 
器 在 设备 的 网 络 上 设置 了 一 个 云 节 点 。 系 统 将 数据 同步 到 直 连 的 设备 、 云 节点 和 通过 Wi-Fi 连 
接 到 云 节点 的 可 穿戴 设备 。 








| Wi-Fi 
Mobile data/Wi-Fi | 
4 
Bluetooth 
" 





Figure 1. 一 个 包含 手持 和 可 穿戴 设备 节点 的 实例 网 络 


Lessons 


访问 可 穿戴 数据 层 
这 节 课 展示 了 如 何 创 建 一 个 客户 端 来 访问 数据 层 API 。 
同步 数据 单元 


数据 元 是 存储 在 一 个 复制 而 来 的 数据 仓库 中 的 对 象 ， 该 仓库 可 自动 由 手持 设备 同步 到 可 穿戴 
设备 。 


传输 资源 


Asset 是 典型 地 用 来 传输 图 像 和 媒体 二 进 制 数据 。 


发 送 与 接收 消息 
消息 被 设计 为 自动 跟踪 的 消息 ， 可 以 在 手持 与 可 穿戴 设备 间 来 回 传送 。 
处 理 数据 层 的 事件 


获知 数据 层 的 变化 与 事件 。 


访问 可 穿戴 数据 层 


编写 :wly2014 - Æ X: http://developer.android.com/training/wearables/data- 
layer/accessing.html 


调用 数据 层 APl， 需 创建 一 个 GoogleApiClient 实例 ， 所 有 Google Play services APls 的 主要 
AU o 


GoogleApiClient 提供 了 一 个 易于 创建 客户 端 实例 的 builder。 最 简单 的 GoogleApiClient 如 下 : 
FT 


Note: 目前 ， 此 小 client 仅 足以 能 启动 。 但 是 ， 更 多 创建 GoogleApiClient， 实 现 回 调 方 法 
和 处 理 错误 等 内 容 ， 详 见 Accessing Google Play services APIs ° 


GoogleApiClient mGoogleApiClient = new GoogleApiClient.Builder(this) 
.addConnectionCallbacks(new ConnectionCallbacks() { 
@Override 
public void onConnected(Bundle connectionHint) { 
Log.d(TAG, "onConnected: " + connectionHint) ; 
// Now you can use the Data Layer API 
} 
@Override 
public void onConnectionSuspended(int cause) { 
Log.d(TAG, "onConnectionSuspended: " + cause); 
} 
}) 


.addOnConnectionFailedListener(new OnConnectionFailedListener() { 
@Override 
public void onConnectionFailed(ConnectionResult result) { 
Log.d(TAG, "onConnectionFailed: " + result); 


j 


}) 
// Request access only to the Wearable API 


.addApi(Wearable.API) 
.build(); 


Important: 如 果 我 们 添加 多 个 API 到 一 个 GoogleApiClient， 那 么 可 能 会 在 没有 安装 
Android Wear app 的 设备 上 遇 到 连接 错误 。 为 了 连接 错误 ， 调 用 addApilfAvailable() 方 
法 ， 并 以 Wearable API 为 参数 传 进 该 方法 ， 从 而 表明 client 应 该 处 理 缺 失 的 API。 更 多 的 
信息 ， 请 见 Access the Wearable API. 


在 使 用 数据 层 API 之 前 ， 通 过 调用 connect()) 方 法 进行 连接 ， 如 Start a Connection 中 所 述 。 
当 系 统 为 我 们 的 客户 端 调用 了 onConnected()) 方法 ， 我 们 就 可 以 使 用 数据 层 API 了 。 
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访问 可 穿戴 数据 层 
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同步 数据 单元 


编写 :Wly2014 - 原文 : http://developer.android.com/training/wearables/data-layer/data- 
items.html 


Dataltem 是 指 系 统 用 于 同步 手持 设备 与 可 穿戴 设备 间 数 据 的 接口 。 一 个 Dataltem 通 常 包括 以 
下 几 点 : 
。 Pyload - 一 个 字 节 数组 ， 我 们 可 以 用 来 设置 任何 数据 ， 让 我 们 的 对 象 序列 化 和 反 序 列 
化 。Pyload 的 大 小 限制 在 100k 之 内 。 
e Path - 唯一 且 以 前 斜 线 开 头 的 字符 串 〈 如 : "/path/to/data") 。 
通常 不 直接 实现 Dataltem， 而 是 : 


创建 一 个 PutdataRequest 对 象 ， 指 明 一 个 字符 串 路 径 以 唯一 确定 该 item © 
调用 setData()) 方 法 设置 Pyload ° 

调用 DataApi.putDataltem() 方 法 ， 请 求 系统 创建 数据 元 。 

当 请 求 数据 元 的 时 候 ， 系 统 会 返回 正确 实现 Dataltem 接 口 的 对 象 。 


FON 一 


然而 ， 我 们 建议 使 用 Data Map 来 显示 装 在 一 个 易 用 的 类 似 Bundle 接 口中 的 数据 元 ， 而 不 是 用 
setData() 来 处 理 原始 字 节 。 


用 Data Map 同步 数据 


使 用 DataMap 类 ， 将 数据 元 处 理 为 Android Bundle 的 形式 ， 因 此 会 完成 对 象 的 序列 化 和 反 序 
列 化 ， 我 们 就 可 以 以 键 值 对 (key-value) 的 形式 操纵 数据 。 


如 何 使 用 data map : 


创建 一 个 PutDataMapRequest 对 象 ， Cod bn o 
Note: 数据 元 的 路 径 字符 串 是 唯一 确定 的 ， 这 样 能 够 使 我 们 从 连接 任意 一 端 访问 数 
据 元 。 ee 个 适 
合 数据 结构 的 路 径 方案 。 


调用 PutDataMapRedquest.getDataMap()) 获 取 一 个 我 们 可 以 使 用 的 data map 对 象 。 
使 用 put...() 方 法 ， 如 : putString()， 为 data map 设 置 数据 。 
调用 PutDataMapRequest.asPutDataRequest()) 获 得 PutDataRequest 对 象 。 
调用 DataApi.putDataltem() 请 求 系统 创 aae o 
Note: 如 果 手 机 和 可 穿戴 设备 没有 连接 ， 数 据 会 缓冲 并 在 重新 建立 连接 时 同步 


ar om 


接 下 的 例子 中 的 increasecounter() 方法 展示 了 如 何 创建 一 个 data map， 并 设置 数据 : 


public class MainActivity extends Activity implements 
DataApi.DataListener, 
GoogleApiClient.ConnectionCallbacks, 
GoogleApiClient.OnConnectionFailedListener { 


private static final String COUNT KEY - "com.example.key.count"; 


private GoogleApiClient mGoogleApiClient; 
private int count = 0; 


// Create a data map and put data in it 
private void increaseCounter() { 
PutDataMapRequest putDataMapReq = PutDataMapRequest.create("/count"); 
putDataMapReq.getDataMap().putInt(COUNT_KEY, count++); 
PutDataRequest putDataReq = putDataMapReq.asPutDataRequest(); 
PendingResult<DataApi.DataItemResult> pendingResult = 
Wearable.DataApi.putDataItem(mGoogleApiClient, putDataReq); 


有 关 控 制 PendingResult 对 象 的 更 多 信息 ， 请 参见 Wait for the Status of Data Layer Calls 。 


监听 数据 元 事件 


如 果 数 据 层 连接 的 一 端 数据 发 生 改 变 ， 我 们 很 可 能 想 要 被 告知 在 连接 的 另 一 端 发 生 的 任何 改 
变 。 我 们 可 以 通过 实现 一 个 数据 元 事件 的 监听 器 来 完成 。 


当 定 义 在 上 一 个 例子 中 的 counter 的 值 发 生 改 变 时 ， 下 面 例子 的 代码 片段 能 够 通知 我 们 的 
app ° 


public class MainActivity extends Activity implements 
DataApi.DataListener, 
GoogleApiClient.ConnectionCallbacks, 
GoogleApiClient.OnConnectionFailedListener { 


private static final String COUNT KEY = "com.example.key.count"; 


private GoogleApiClient mGoogleApiClient; 
private int count = 0; 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
setContentView(R.layout.activity main); 


mGoogleApiClient = new GoogleApiClient.Builder(this) 
.addApi(Wearable.API) 
.addConnectionCallbacks(this) 
.addOnConnectionFailedListener(this) 
.build(); 


@Override 

protected void onResume() { 
super.onStart(); 
mGoogleApiClient.connect(); 


@Override 
public void onConnected(Bundle bundle) { 
Wearable.DataApi.addListener(mGoogleApiClient, this); 


@Override 

protected void onPause() { 
super .onPause(); 
Wearable.DataApi.removeListener(mGoogleApiClient, this); 
mGoogleApiClient.disconnect(); 


@Override 
public void onDataChanged(DataEventBuffer dataEvents) { 
for (DataEvent event : dataEvents) { 
if (event.getType() == DataEvent.TYPE_CHANGED) { 
// DataItem 改变 了 
DataItem item = event.getDataItem(); 
if (item.getUri().getPath().compareTo("/count") == 0) { 
DataMap dataMap = DataMapItem.fromDataItem(item).getDataMap(); 
updateCount (dataMap. getInt(COUNT_KEY) ); 


} 
} eise if (event.getType() == DataEvent.TYPE DELETED) { 
// DataItem 删除 了 


// 我 们 的 更 新 Count 的 方法 
private void updateCount(int c) { ... } 


这 个 activity 是 实现 了 Dataltem.DataListener 接口 。 该 activity 在 onconnected() 方法 中 增加 自 
身 成 为 数据 元 事件 的 监听 器 ， 并 在 onPause() 方法 中 移 除 监听 器 。 


我 们 也 可 以 用 一 个 service 实 现 监 听 ， 请 见 监听 数据 层 事件 。 


同步 数据 单元 
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传 Ar à 1i T 源 


编写 :Wly2014 - 原文 : http://developer.android.com/training/wearables/data- 
layer/assets.html 


为 了 通过 蓝牙 发 送 大 量 的 二 进 制 数据 ， 比 如 图 片 ， 要 将 一 个 Asset 附 加 到 数据 元 上 ， 并 放 入 复 
制 而 来 的 数据 库 中 。 


Assets 能 够 自动 地 处 理 数据 缓存 以 避免 重复 发 送 ， 保 护 蓝 牙 带 宽 。 一 般 的 模式 是 : 手持 设备 
下 载 图 像 ， 将 图 片 压 缩 到 适合 在 可 穿戴 设备 上 显示 的 大 小 ， 并 以 Asset 传 给 可 穿戴 设备 。 下 面 
的 例子 演示 此 模式 。 


Note: 尽管 数据 元 的 大 小 限制 在 100KB， 但 资源 可 以 任意 大 。 然 而 ， 传 输 大 量 资源 会 多 
方面 地 影响 用 户 体验 ， 因 此 ， 当 传输 大 量 资源 时 ， 要 测试 我 们 的 应 用 以 保证 它 有 良好 的 
用 户 体验 。 


传输 资源 


在 Asset 类 中 使 用 creat..() 方法 创建 资源 。 下 面 ， 我 们 将 一 个 bitmap 转 化 为 字 节 流 ， 然 后 调 
用 creatFromBytes()) 方 法 创建 资源 。 


private static Asset createAssetFromBitmap(Bitmap bitmap) { 
final ByteArrayOutputStream byteStream = new ByteArrayOutputStream(); 
bitmap.compress(Bitmap.CompressFormat.PNG, 100, byteStream); 
return Asset.createFromBytes(byteStream.toByteArray()); 


创建 资源 后 ， 使 用 DataMap 或 者 PutDataRepuest 类 中 的 putasset() 方法 将 其 附加 到 数据 
元 上 ， 然 后 用 putDataltem() 方法 将 数据 元 放 入 数据 库 。 


使 用 PutDataRequest 


Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.image); 
Asset asset - createAssetFromBitmap(bitmap); 

PutDataRequest request = PutDataRequest.create("/image"); 
request.putAsset("profileImage", asset); 
Wearable.DataApi.putDataltem(mGoogleApiClient, request); 


使 用 PutDataMapRequest 


Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.image); 

Asset asset - createAssetFromBitmap(bitmap); 

PutDataMapRequest dataMap = PutDataMapRequest.create("/image"); 

dataMap.getDataMap().putAsset("profileImage", asset) 

PutDataRequest request - dataMap.asPutDataRequest(); 

PendingResult<DataApi.DataItemResult> pendingResult = Wearable.DataApi 
.putDataltem(mGoogleApiClient, request); 


创建 资源 后 ， 我 们 可 能 需要 在 另 一 连接 端 读 取 资源 。 以 下 是 如 何 实现 回调 以 发 现 资源 变化 和 
提取 Asset 对 象 。 


@Override 
public void onDataChanged(DataEventBuffer dataEvents) { 
for (DataEvent event : dataEvents) { 
if (event.getType() == DataEvent.TYPE_CHANGED && 
event.getDataItem().getUri().getPath().equals("/image")) { 

DataMapItem dataMapItem = DataMapItem.fromDataItem(event.getDataItem()); 
Asset profileAsset = dataMapItem.getDataMap().getAsset("profileImage"); 
Bitmap bitmap = loadBitmapFromAsset(profileAsset); 
// Do something with the bitmap 


public Bitmap loadBitmapFromAsset(Asset asset) { 
if (asset == null) { 
throw new IllegalArgumentException("Asset must be non-null"); 
} 
ConnectionResult result = 
mGoogleApiClient.blockingConnect(TIMEOUT MS, TimeUnit.MILLISECONDS); 
if (!result.isSuccess()) { 
return null; 
} 
// convert asset into a file descriptor and block until it's ready 
InputStream assetInputStream = Wearable.DataApi.getFdForAsset( 
mGoogleApiClient, asset).await().getInputStream(); 
mGoogleApiClient.disconnect(); 


if (assetInputStream == null) { 
Log.w(TAG, "Requested an unknown Asset."); 
return null; 

} 

// decode the stream into a bitmap 

return BitmapFactory.decodeStream(assetInputStream) ; 


传输 资源 
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发 送 与 接收 消息 


编写 :Wly2014 - 原文 : http://developer.android.com/training/wearables/data- 
layer/messages.html 


使 用 MessageApi 发 送 消息 ， 要 附加 以 下 几 项 : 


e 任 一 payload (可 选 ) 
e 唯一 标识 消息 动作 的 路 径 


ee 。Messages 是 单 向 交流 
机 制 ， 这 有 利于 远程 进程 调用 (RPC)， 比 如 : 发 送 消息 到 可 穿戴 设备 以 开启 activity » 


多 个 可 穿戴 设备 可 以 连接 到 一 台 用 户 的 手持 设备 。 在 网 络 中 每 个 已 连接 的 设备 被 视 为 一 个 节 

点 (node) 。 由 于 有 多 个 已 连接 的 设备 ， 我 们 必须 考虑 哪个 节点 收 到 消息 。 例 如 ， 在 一 个 在 

nr 数据 的 语音 转录 应 用 中 ， 我 们 应 该 发 送 消息 到 一 个 具有 处 理 能 力 和 电 
容量 的 节点 来 处 理 请 求 ， 例 如 一 个 手持 式 设备 。 


Note: Google Play services 7.3.0 版 之 前 ， 一 次 只 有 一 个 可 穿戴 设备 可 以 连接 到 手持 设 
备 。 我 们 需要 将 现 有 的 代码 升级 ， 以 考虑 到 多 个 连接 节点 的 功能 。 如 果 我 们 不 作出 修 
改 ， 那 么 我 们 的 消息 可 能 不 会 传 到 想 要 的 设备 。 


发 送 消息 


一 个 可 穿戴 应 用 可 以 为 用 户 提供 如 语音 下 
说 话 ， 然 后 就 会 将 语音 保存 成 一 个 笔记 。 由 于 一 个 可 穿戴 设备 通常 没有 足够 的 处 理 能 力 和 电 

量 来 处 理 语音 转录 activity， 所 以 应 用 应 该 将 这 个 工作 留 给 一 个 更 加 有 能 力 的 、 已 连接 的 
indio o 


下 面 几 个 小 节 介 绍 如何 通 知 那 些 可 以 处 理 activity 请 求 的 设备 节点 ， 发 现 有 能 力 满足 请 求 的 节 
点 ， 并 发 送 消息 给 那些 节点 。 


通知 节点 功能 


使 用 MessageApi 类 发 送 请 求 ， 来 从 一 个 可 穿戴 设备 启动 一 个 手持 设备 的 activity。 由 于 一 个 
手持 式 设备 可 以 连接 多 个 可 穿戴 设备 ， (uM Ne a 车 接 的 节点 是 否 有 能 
力 启动 activity。 在 我 们 的 手持 式 应 用 中 ， 通 知 其 它 节 点 : 我 们 的 手持 式 应 用 所 在 的 节点 提供 
了 上 述 指定 的 功能 。 


为 了 把 我 们 的 手持 式 应 用 的 功能 通知 其 它 节点 ， 需 要 : 


1. 在 工程 的 res/values/ H 录 下 创建 一 个 名 为 wear.xml 的 XML 文件 。 
2. Æ wear .xml 文件 中 添加 一 个 名 为 android wear capabilities 的 资源 。 
3. 定义 设备 可 以 提供 的 功能 。 


Note: 功能 是 我 们 自 定 义 的 字符 串 ， 它 在 我 们 的 应 用 中 必须 是 唯一 的 。 


下 面 这 个 例子 介绍 了 如 何 将 一 个 名 为 voice transcription 的 功能 添加 到 wear.xml 中 : 


«resources» 
<string-array name-"android wear capabilities"- 
<item>voice_transcription</item> 
</string-array> 
</resources> 


检索 具有 相关 功能 的 节点 


首先 ， 我 们 可 以 通过 调用 CapabilityApi.getCapability() 方法 来 检测 具有 相关 功能 的 节点 。 下 
面 的 例子 介绍 了 如 何 手 动 检索 具有 voice transcription 功能 的 节点 : 


private static final String 
VOICE TRANSCRIPTION CAPABILITY NAME - "voice transcription"; 


private GoogleApiClient mGoogleApiClient; 


private void setupVoiceTranscription() { 
CapabilityApi.GetCapabilityResult result - 
Wearable.CapabilityApi.getCapability( 
mGoogleApiClient, VOICE TRANSCRIPTION CAPABILITY NAME, 
CapabilityApi.FILTER REACHABLE).await(); 


updateTranscriptionCapability(result.getCapability()); 


为 了 在 连接 到 可 穿戴 设备 的 时 候 检 测 有 能 力 的 节点 ， 注 册 一 个 
CapabilityApi.CapabilityListener() 实例 到 GoogleApiClient。 下 面 的 例子 介绍 了 如 何 注 册 该 监 
听 器 和 检索 具有 voice transcription 功能 的 节点 。 


private void setupVoiceTranscription() { 


CapabilityApi.CapabilityListener capabilityListener - 
new CapabilityApi.CapabilityListener() { 
@Override 
public void onCapabilityChanged(CapabilityInfo capabilityInfo) { 
updateTranscriptionCapability(capabilityInfo); 


}; 


Wearable.CapabilityApi.addCapabilityListener( 
mGoogleApiClient, 
capabilityListener, 
VOICE TRANSCRIPTION CAPABILITY NAME); 


Note: 如 果 我 们 创建 一 个 继承 WearableListenerService 的 service 来 检测 功能 的 变化 ， 
我 们 可 能 要 重 写 onConnectedNodes()) 方法 来 监听 细微 的 连接 细节 ， 例 如 ， 一 个 可 穿戴 
设备 与 手持 式 设备 从 Wi-Fi 连 接 切 换 到 蓝牙 连接 。 关 于 一 个 实现 的 例子 ， 请 查看 在 
FindMyPhone 示例 中 的 DisconnectListenerService 类 。 更 多 关于 如 何 监听 重要 事件 的 
内 容 ， 请 见 监听 数据 层 事 件 。 


检测 到 有 能 力 的 节点 之 后 ， 需 要 确定 将 消息 发 送 到 哪里 。 我 们 需要 选择 与 可 穿戴 设备 邻近 的 
节点 ， 这 样 可 以 最 小 化 多 个 节点 间 的 消息 路 由 。 一 个 邻 a 
接 的 节点 。 调 用 Node.isNearby()) 来 确定 一 个 节点 是 否 近 的 。 


下 面 的 例子 介绍 了 如 何 确定 最 佳节 点 


private String transcriptionNodeId = null; 


private void updateTranscriptionCapability(CapabilityInfo capabilityInfo) { 
Set«Node» connectedNodes - capabilityInfo.getNodes(); 


transcriptionNodeId = pickBestNodeId(connectedNodes); 


private String pickBestNodeId(Set«Node» nodes) { 

String bestNodeId = null; 
// Find a nearby node or pick one arbitrarily 
for (Node node : nodes) { 

if (node.isNearby()) { 

return node.getId(); 
} 
bestNodeId = node.getId(); 


} 
return bestNodeId; 


传送 消息 
一 旦 我 们 确定 了 最 佳节 点 ， 使 用 MessageApi 发 送 消息 。 


下 面 的 例子 介绍 ee 到 具有 语音 转录 功能 的 节点 。 在 我 们 试图 
发 送 消息 之 前 ， 需 要 判断 节点 是 否 可 用 。 这 个 调用 是 同步 的 ， 它 在 系统 将 传送 的 消息 放 到 队 
列 前 会 一 直 阻 塞 。 


Note: 一 个 成 功 结果 码 并 不 保证 消息 是 否 传 送 成 功 。 如 果 我 们 的 应 用 需要 数据 的 可 靠 
性 ， 那 么 使 用 Dataltem 对 象 或 者 ChannelApi 类 在 设备 间 发 送 数 据 。 


public static final String VOICE TRANSCRIPTION MESSAGE PATH = "/voice transcription"; 


private void requestTranscription(byte[] voiceData) { 
if (transcriptionNodeId != null) { 
Wearable.MessageApi.sendMessage(googleApiClient, transcriptionNodeId, 
VOICE TRANSCRIPTION MESSAGE PATH, voiceData).setResultCallback( 
new ResultCallback() { 
@Override 
public void onResult(SendMessageResult sendMessageResult) { 
if (!sendMessageResult.getStatus().isSuccess()) { 
// Failed to send message 


); 
} else { 
// Unable to retrieve node with transcription capability 


Note: 阅读 Communicate with Google Play Services 了 解 更 多 关于 异步 和 同步 调用 ， 以 
及 何 时 使 用 哪个 。 


我 们 还 可 以 广播 消息 给 所 有 已 连接 的 节点 。 为 了 获得 我 们 可 以 发 送 消息 的 已 连接 节点 ， 需 要 
实现 下 面 的 代码 : 


private Collection<String> getNodes() { 
HashSet <String>results = new HashSet<String>(); 
NodeApi.GetConnectedNodesResult nodes = 
Wearable.NodeApi.getConnectedNodes(mGoogleApiClient).await(); 
for (Node node : nodes.getNodes()) { 
results.add(node.getId()); 
} 


return results; 


接收 消息 


为 了 在 收 到 消息 时 被 提醒 ， 我 们 可 以 实现 MessageListener 接口 来 提供 消息 事件 的 监听 。 然 
后 ， 我 们 需要 在 MessageApi.addListener() 方法 中 注册 监听 。 这 个 例子 展示 如 何 通过 检查 
VOICE TRANSCRIPTION MESSAGE PATH 来 实现 监听 器 。 如 果 该 条 件 是 true， 就 会 启动 特定 的 
activity 来 处 理 语音 数据 。 


@Override 
public void onMessageReceived(MessageEvent messageEvent) { 
if (messageEvent.getPath().equals(VOICE TRANSCRIPTION MESSAGE PATH)) { 
Intent startIntent - new Intent(this, MainActivity.class); 
startIntent.addFlags(Intent.FLAG ACTIVITY NEW TASK); 
startIntent.putExtra("VOICE DATA", messageEvent.getData()); 
startActivity(startIntent); 


这 仅 是 实现 更 多 细节 的 一 小 段 。 关 于 如 何在 service 或 activity 实现 完整 的 监听 ， 请 参见 监听 
数据 传输 层 事件 。 


处 理 数 据 层 的 事件 


编写 :wly2014 - 原文 : http://developer.android.com/training/wearables/data- 
layer/events.html 


当做 出 数据 层 上 的 调用 时 ， 我 们 可 以 得 到 它 完 成 后 的 调用 状态 ， 也 可 以 用 监听 器 监听 到 调用 
最 终 实现 的 改变 。 


等 待 数据 层 调 用 的 状态 


注意 到 ， 调 用 数据 层 API， 有 时 会 返回 PendingResult， 如 putDataltem() » PendingResult 一 
被 创建 ， 操 作 就 会 在 后 台 排 列 等 候 。 之 后 我 们 若 无 动 作 ， 这 些 操 作 最 终 会 默默 完成 。 然 而 ， 
通常 要 处 理 操 作 完 成 后 的 结果 ，PendingResult 能 够 让 我 们 同步 或 异步 地 等 待 结果 


异步 调用 


若 代 码 运 行 在 主 Ul 线 程 上 ， 不 要 让 数据 层 API 调 用 阻塞 Ul。 我 们 可 以 增加 一 个 回调 到 
PendingResult 对 象 来 运行 异步 调用 ， 该 回调 函数 将 在 操作 完成 时 触发 。 


pendingResult.setResultCallback(new ResultCallback<DataItemResult>() { 
@Override 
public void onResult(final DataItemResult result) { 
if(result.getStatus().isSuccess()) { 
Log.d(TAG, "Data item set: " + result.getDataItem().getUri()); 


3): 


同步 调用 


如 果 代 码 是 运行 在 后 台 服 务 的 一 个 独立 的 处 理 线程 上 (WearableListenerService 的 情况 ) > 
则 调用 导致 的 阻塞 没 影响 。 在 这 种 情况 下 ,我 们 可 以 用 PendingResult 对 象 调用 await())， 它 将 
阻塞 至 请 求 完成 ,并 返回 一 个 Result 对 象 : 


DataItemResult result = pendingResult.await(); 
if(result.getStatus().isSuccess()) 1 
Log.d(TAG, "Data item set: " + result.getDataItem().getUri()); 


} 


监听 数据 层 事件 

因为 数据 层 在 手持 和 可 穿戴 设 备 间 同步 并 发 送 数据 ， 所 以 通常 要 监听 重要 事件 ， 例 如 创建 数 
据 元 ， 接 收 消息 ， 或 连接 可 穿戴 设备 和 手机 。 

对 于 监听 数据 层 事件 ， 有 两 种 选择 : 


e 创建 一 个 继承 自 WearableListenerService 的 service。 
e 创建 一 个 实现 DataApi.DataListener 接口 的 activity ° 


通过 这 两 种 选择 ， 为 我 们 感 兴 趣 的 事件 重 写 数据 事件 回调 方法 。 


使 用 WearableListenerService 


通常 ， 我 们 在 手持 设备 和 可 穿戴 设备 上 都 创建 该 service 的 实例 。 如 果 我 们 不 关心 其 中 一 个 应 
用 中 的 数据 事件 ， 就 不 需要 在 相应 的 应 用 中 实现 此 service。 


例如 ， 我 们 可 以 在 一 个 手持 设备 应 用 程序 上 操作 数据 元 对 象 ， 可 穿戴 设备 应 用 监听 这 些 更 新 
来 更 新 自身 的 UI。 而 可 穿戴 不 更 新 任何 数据 元 ， 所 以 手持 设备 应 用 不 监听 任何 可 穿戴 式 设备 
应 用 的 数据 事件 。 


我 们 可 以 用 WearableListenerService 监听 如 下 事件 : 


e onDataChanged()) - 当 数据 元 对 象 创建 ， 更 改 ， 删 除 时 调用 。 一 连接 端的 事件 将 触发 两 
端的 回调 方法 。 

e onMessageReceived()) - 消息 从 一 连接 端 发 出 ， 在 另 一 连接 端 触 发 此 回调 方法 。 

e onPeerConnected()) 和 onPeerDisconnected()) - 当 与 手持 或 可 穿戴 设备 连接 或 断 开 时 调 
用 。 一 连接 端 连接 状态 的 改变 会 在 两 端 触发 此 回调 方法 。 


创建 WearableListenerService， 我 们 需要 : 


1. 创建 一 个 继承 自 WearableListenerService 的 类 。 

2， 监 听 我 们 关心 的 事件 ， 比 如 onDataChanged()) ° 

3. 在 Android manifest 中 声明 一 个 intent filter， 把 我 们 的 WearableListenerService 通知 给 系 
统 。 这 样 允许 系统 在 需要 时 绑 定 我 们 的 service 。 


下 例 展示 如 何 实现 一 个 简单 的 WearableListenerService : 


public class DataLayerListenerService extends WearableListenerService { 


private static final String TAG = "DataLayerSample"; 
private static final String START ACTIVITY PATH - "/start-activity"; 
private static final String DATA ITEM RECEIVED PATH - "/data-item-received"; 


@Override 
public void onDataChanged(DataEventBuffer dataEvents) { 
if (Log.isLoggable(TAG, Log.DEBUG)) { 
Log.d(TAG, "onDataChanged: ”+ dataEvents); 
} 
final List events = FreezableUtils 
.freezeIterable(dataEvents); 


GoogleApiClient googleApiClient - new GoogleApiClient.Builder(this) 
.addApi(Wearable.API) 
.build(); 


ConnectionResult connectionResult - 
googleApiClient.blockingConnect(30, TimeUnit.SECONDS); 


if (!connectionResult.isSuccess()) { 
Log.e(TAG, "Failed to connect to GoogleApiClient."); 
return; 


// Loop through the events and send a message 
// to the node that created the data item. 
for (DataEvent event : events) { 

Uri uri = event.getDataItem().getUri(); 


// Get the node id from the host value of the URI 

String nodeId - uri.getHost(); 

// Set the data of the message to be the bytes of the URI 
byte[] payload - uri.toString().getBytes(); 


// Send the RPC 
Wearable.MessageApi.sendMessage(googleApiClient, nodeId, 
DATA ITEM RECEIVED PATH, payload); 


3% X: Android mainfest 中 相应 的 intent filter : 


«service android:name=".DataLayerListenerService"> 
<intent-filter> 
<action android:name="com.google.android.gms.wearable.BIND_LISTENER" /> 
«/intent-filter» 


«/service» 


数据 层 回调 权限 


为 了 在 数据 层 事 件 上 向 我 们 的 应 用 传送 回调 方法 ，Google Play services 绑 定 到 我 们 的 
WearableListenerService， 并 通过 |PC 调 用 回调 方法 。 这 样 的 结果 是 ， 我 们 的 回调 方法 继承 了 
调用 进程 的 权限 。 


如 果 我 们 想 在 一 个 回调 中 执行 权限 操作 ， 安 全 检查 会 失败 ， 因 为 回调 是 以 调用 进程 的 身份 运 
行 ， 而 不 是 应 用 程序 进程 的 身份 运行 。 

为 了 解决 这 个 问题 ， 在 进入 IPC 后 使 用 clearCallingldentity()) 重 置身 份 ， 当 完成 权限 操作 后 ， 
使 用 restoreCallingldentity()) 恢复 身份 : 


long token = Binder.clearCallingIdentity(); 


try { 
performOperationRequiringPermissions(); 


} finally { 
Binder .restoreCallingIdentity(token) ; 


} 


使 用 一 个 Listener Activity 


如 果 我 们 的 应 用 只 关心 当 用 户 与 应 用 交互 时 产生 的 数据 层 事件 ， 并 且 不 需要 一 个 长 时 间 运 行 
的 service 来 处 理 每 一 次 数据 的 改变 ， 那 么 我 们 可 以 在 一 个 activity 中 通过 实现 如 下 一 个 和 多 
个 接口 来 监听 事件 : 


e DataApi.DataListener 
e MessageApi.MessageListener 
e NodeApi.NodeListener 


创建 一 个 activity 监听 数据 事件 ， 需 要 : 


实现 所 需 的 接口 。 
在 onCreate(Bundle)) 中 创建 GoogleApiClient 实例 。 
在 onStart()) 中 调用 connect()) 将 客户 端 连接 到 Google Play services ° 
当 连 接 到 Google Play services% > AHMA onConnected())。 这 里 是 我 们 调用 
DataApi.addListener() » MessageApi.addListener() 或 NodeApi.addListener()， 以 告知 
Google Play services 我 们 的 activity 要 监听 数据 层 事件 的 地 方 。 
5. 在 onStop()) 中 ， 用 DataApi.removeListener()), MessageApi.removeListener()) 

或 NodeApi.removeListener()) 注销 监听 » 
6. 基于 我 们 实现 的 接口 继而 实现 onDataChanged(), onMessageReceived(), 
onPeerConnected() 和 onPeerDisconnected() ° 


FON 一 


这 是 实现 DataApi.DataListener 的 例子 : 


public class MainActivity extends Activity implements 
DataApi.DataListener, ConnectionCallbacks, OnConnectionFailedListener { 


private GoogleApiClient mGoogleApiClient; 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 


setContentView(R.layout.main); 

mGoogleApiClient - new GoogleApiClient.Builder(this) 
.addApi(Wearable.API) 
.addConnectionCallbacks(this) 
.addOnConnectionFailedListener(this) 
.build(); 


QOverride 
protected void onStart() { 
super.onStart(); 
if (!mResolvingError) { 
mGoogleApiClient.connect(); 


@Override 
public void onConnected(Bundle connectionHint) { 
if (Log.isLoggable(TAG, Log.DEBUG)) { 
Log.d(TAG, "Connected to Google Api Service"); 


} 

Wearable.DataApi.addListener(mGoogleApiClient, this); 
^ 
QOverride 


protected void onStop() 1 
if (null != mGoogleApiClient && mGoogleApiClient.isConnected()) ( 
Wearable.DataApi.removeListener(mGoogleApiClient, this); 
mGoogleApiClient.disconnect(); 


} 
super.onStop(); 
} 
@Override 


public void onDataChanged(DataEventBuffer dataEvents) { 
for (DataEvent event : dataEvents) { 
if (event.getType() == DataEvent.TYPE_DELETED) { 
Log.d(TAG, "DataItem deleted: " + event.getDataItem().getUri()); 
} else if (event.getType() == DataEvent.TYPE_CHANGED) { 
Log.d(TAG, "DataItem changed: " + event.getDataItem().getUri()); 


处 理 数 据 层 的 事件 
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编写 :heray1990 - Æ X: http://developer.android.com/training/wearables/watch- 
faces/index.html 


Android Wear 的 表盘 是 一 个 动态 的 数字 画布 ， 它 用 颜色 、 动 画 和 相关 的 上 下 文 信息 来 表示 时 
la] » Android Wear companion app 提供 了 不 同 风格 和 形状 的 表盘 。 当 用 户 选 择 可 穿戴 设备 应 
用 或 者 配套 应 用 上 可 用 的 表盘 ， 可 穿戴 设备 会 提供 表盘 的 预览 并 让 用 户 设置 选项 。 


Android Wear 允许 我 们 为 Wear 设备 创建 自 定义 的 表盘 。 当 用 户 安装 一 个 包含 表 瘟 的 可 穿戴 
应 用 的 手持 式 应 用 时 ， 它 们 可 以 在 手持 式 设 备 上 的 Android Wear 配套 应 用 和 在 可 穿戴 设备 上 
的 表盘 选择 器 中 使 用 。 


这 个 课程 教 我 们 实现 自 定义 表盘 并 将 它们 打包 进 一 个 可 穿戴 应 用 。 这 节 课 还 履 盖 设计 方面 的 
考虑 和 实现 提示 ， 从 而 确保 我 们 的 设计 整合 到 系统 Ul 并 且 节 能 。 


Note: 我 们 推荐 使 用 Android Studio 做 Android Wear 开发 ， 它 提供 工程 初始 配置 ， 库 包 
含 和 方便 的 打包 流程 ， 这 些 在 ADT 中 是 没有 的 。 这 系列 教程 假定 你 正在 使 用 Android 
Studio ° 


Lesson 


设计 表盘 

学 习 如 何 设 计 一 个 可 以 工作 在 Android Wear 设备 上 的 表盘 。 
构建 表盘 服务 

学 习 如 何在 表盘 的 生命 周期 期 间 响 应 重要 的 时 间 。 
绘制 表盘 

学 习 如 何在 一 个 Wear 设备 的 屏幕 上 绘制 表盘 。 
在 表盘 上 显示 信息 

学 习 如 何 将 上 下 文 信息 集 成 到 表盘 中 。 

提供 配置 Activity 

学 习 如 何 创建 带 有 可 配置 参数 的 表盘 。 

定位 常见 的 问题 


学 习 如 何在 开发 表盘 的 时 候 修改 常见 的 问题 。 


优化 性 能 和 电池 使 用 时 间 


学 习 如 何 提高 动画 的 帧 速率 和 节能 


o 
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"JL ` k 
设计 表盘 
编写 :heray1990 - Æ X: http://developer.android.com/training/wearables/watch- 


faces/designing.html 


类 似 于 设计 传统 的 表盘 ， 创 建 Android Wear £X & X — ^ 74 B6 E RAY 18] 692 o Android 
Wear 设备 为 表盘 提供 了 高 级 的 功能 ， 我 们 可 以 运用 这 些 功 能 到 我 们 的 设计 当中 ， 例 如 鲜艳 的 
色彩 、 动 态 的 背景 、 动 画 和 数据 整合 。 然 而 ， 我 们 必须 考虑 到 很 多 其 它 设 计 上 的 因素 。 


这 节 课 总 结 了 设计 表盘 需要 考虑 的 因素 和 通用 准则 。 更 多 关于 这 方面 的 内 容 ， 请 见 Watch 
Faces for Android Wear 设计 指引 。 


守 设 计 准 侧 
当 我 们 设计 表盘 的 外 观 和 表盘 需要 向 用 户 表 达 哪 些 类 型 的 信息 的 时 候 ， 请 考虑 一 下 这 些 设计 
准 侧 : 
为 方形 和 圆 形 的 设备 作出 规划 


我 们 的 设计 应 该 可 以 运行 在 方形 和 圆 形 的 Android Wear 设备 上 ， 和 包括 那些 使 用 感知 形状 的 
Layout 的 设备 。 


支持 所 有 的 显示 模式 


我 们 的 表盘 应 该 支持 有 限 颜 色 的 环境 模式 (ambient mode) 和 全 彩色 动画 的 交互 模式 
(interactive mode) 。 


优化 特殊 屏幕 的 技术 


在 环境 模式 下 ， 表 盘 应 该 让 大 部 分 像素 保持 黑色 。 根 据 屏 幕 技 术 ， 我 们 需要 避免 使 用 大 块 的 
白人 像素， 仅仅 使 用 黑色 和 白色， 并 禁用 反 锯齿 。 


容纳 系统 Ul 组 件 


我 们 的 设计 应 该 确保 系统 指示 图 标 可 见 ， 当 notification cards 出 现在 屏幕 上 的 时 候 用 户 还 可 
以 看 到 时 间 。 


整合 数据 


我 们 的 表盘 可 以 利用 配套 手机 设备 上 的 传感器 和 蜂 富 数 据 连接 ， 来 显示 相关 的 上 下 文 数据 ， 
例如 天 气 或 者 用 户 的 下 一 个 日 程 表 事件 。 


提供 设置 选项 


我 们 可 以 让 用 户 配置 可 穿戴 应 用 或 者 Android Wear 配套 应 用 上 某 些 设计 特征 (如 颜色 和 尺 
d)? 


Mm 
Until Meeting 
with Emma 





Figure 1. 表盘 的 例子 . 


更 多 关于 Android Wear 表盘 的 设计 ， 请 见 Watch Faces for Android Wear 设计 指引 。 


创建 实现 策略 


我 们 需要 决定 如 何 获 得 必要 的 数据 和 将 表盘 绘制 到 可 穿戴 设备 上 。 大 部 
分 实现 方案 由 如 下 部 分 组 成 : 


。 一 幅 或 多 幅 背 景 图 片 
o 接收 需要 数据 的 应 用 代码 
。 绘制 背景 图 片上 的 文本 和 形状 的 应 用 代码 


我 们 一 般 在 交互 模式 和 环境 模式 使 用 两 幅 不 同 的 背景 图 片 。 环 境 模 式 下 的 背景 一 般 是 全 黑 
的 。Android Wear 设备 的 屏幕 密度 (hdpi) 应 该 是 320 x 320 像素 ， 这 样 可 以 同时 兼容 方形 
和 圆 形 设 备 。 背 景 图片 的 四 角 在 圆 形 设 备 上 是 不 可 见 的 。 在 我 们 的 代码 中 ， 我 们 可 以 检测 到 
设备 屏幕 的 尺寸 。 如 果 设 备 的 分 辨 率 比 图 片 的 低 ， 那 么 按 比 例 缩小 背景 图 片 。 为 了 提高 性 

能 ， 我 们 应 该 只 对 背景 图 片 缩放 一 次 并 保存 缩放 后 的 bitmap 。 


我 们 应 该 在 需要 时 运行 代码 来 检索 上 下 文 数据 和 保存 结果 ， 使 得 在 每 次 绘制 表盘 的 时 候 重 用 
数据 。 例 如 ， 我 们 不 需要 每 隔 一 分 钟 去 刷新 一 次 天 气 。 


为 了 增加 电池 使 用 时 间 ， 在 环境 模式 绘制 表盘 的 应 用 代码 应 该 相对 简单 。 在 环境 模式 下 ， 我 
们 通常 用 一 组 有 限 的 颜色 来 绘制 形状 的 轮 廊 。 在 交互 模式 下 ， 我 们 可 以 使 用 全 色彩 、 复 杂 的 
形状 、 渐 变 和 动画 来 绘制 表盘 。 


后 面 的 课程 将 会 介绍 如 何 详细 地 实现 表盘 。 


构建 表盘 服务 


编写 :heray1990 - Æ X: http://developer.android.com/training/wearables/watch- 
faces/service.html 


Android Wear 的 表盘 在 可 穿戴 应 用 中 实现 为 服务 (services) 和 包 。 当 用 户 安装 一 个 包含 表 

盘 的 可 穿戴 应 用 的 手持 式 应 用 时 ， 这 些 表盘 在 手持 式 设备 的 Android Wear 配套 应 用 和 可 穿戴 
表盘 选择 器 中 可 用 。 当 用 户 选择 一 个 可 用 的 表盘 时 ， 可 穿戴 设备 会 显示 表 瘟 并 且 按 需要 调用 

它 的 服务 毁 掉 方法 。 


这 节 课 介绍 如 何 配 置 包含 表盘 的 Android 工程 和 如 何 实现 表盘 服务 


创建 并 配置 工程 


在 Android Studio 中 为 表盘 创建 一 个 Android 工程 ， 需 要 : 


一 人 


打开 Android Studio。 

2. 创建 一 个 新 的 工程 : 
o 如 果 没 有 打开 过 任何 工程 ， 那 么 在 Welcome 界面 中 点 击 New Project ° 
o 如 果 已 经 打开 过 工程 ， 那 么 在 File 菜单 中 选择 New Project 。 

填写 应 用 名 字 ， 然 后 点 击 Next 。 

选择 Phone and Tablet 尺寸 系数 。 

在 Minimum SDK 下 拉 菜 单 选择 API 18 ° 

选择 Wear 尺寸 系数 。 

在 Minimum SDK 下 拉 菜 单 选 择 API 21， 然 后 点 击 Next 。 

选择 Add No Activity 然后 在 接 下 来 的 两 个 界面 点 击 Next 。 

点 击 tien 8 

10. 在 IDE 窗口 点 击 View > Tool Windows > Project ° 


(o 0 400 o 


£ 3b > Android Studio 创建 了 一 个 含有 wear 和 mobile 模块 的 工程 。 更 多 关于 创建 工程 的 
内 容 ， 请 见 Creating a Project ° 


依赖 


Wearable Support 库 提供 了 必要 的 类 ， 我 们 可 以 继承 这 些 类 来 创建 表盘 的 实现 。 需 要 用 
Google Play services client 库 ( play-services 和 play-services-wearable ) 在 配套 设备 和 
含有 可 穿戴 数据 层 API 的 可 穿戴 应 用 之 间 同 步 数 据 项 。 


当 我 们 按照 上 述 的 方法 创建 工程 时 ，Android Studio 会 自动 添加 需要 的 条 目 到 build.gradle 
文件 。 


Wearable Support 库 API 参考 资源 


该 参考 文档 提供 了 用 于 实现 表盘 的 详细 信息 。 详 见 API 参考 文档 。 


在 Eclipse ADT 中 下 载 Wearable Support 库 


如 果 你 使 用 Eclipse ADT， 那 么 请 下 载 Wearable Support = 并 且 将 该 库 作 为 依赖 包含 在 你 的 
工程 当中 。 


声明 权限 


表盘 需要 PROVIDE_BACKGROUND 和 wAKE Lock 权限 。 在 可 穿戴 和 手持 式 应 用 的 manifest 文件 
中 manifest 和 点 下 添加 如 下 权限 : 


«manifest ...> 
«uses-permission 
android:name-"com.google.android.permission.PROVIDE BACKGROUND" /> 
«uses-permission 


android:name-"android.permission.WAKE LOCK" /> 


«/manifest» 


Caution: 手持 式 应 用 必须 包括 所 有 在 可 穿戴 应 用 中 声明 的 权限 。 


实现 服务 和 回调 方法 


Android Wear 的 表盘 实现 为 服务 (services)。 当 表盘 处 于 活动 状态 时 ， 系 统 会 在 时 间 改 变 或 者 
出 现 重要 的 时 间 (如 切换 到 环境 模式 或 者 接收 到 一 个 新 的 通知 ) 的 时 候 调 用 服务 的 方法 。 服 
务实 现 接着 根据 更 新 的 时 间 和 其 它 相 关 的 数据 将 表盘 绘制 到 屏幕 上 。 


实现 一 个 表盘 2 我 们 需要 继承 canvaswatchFaceservice 和 CanvasWatchFaceService.Engine 
类 ， 然 后 重 写 CanvasWatchFaceService.Engine 类 的 回调 方法 。 这 些 类 都 包含 在 Wearable 


Support 库 里 。 


下 面 的 代码 片段 略 述 了 我 们 需要 实现 的 主要 方法 : 


public class AnalogWatchFaceService extends CanvasWatchFaceService ( 


@Override 

public Engine onCreateEngine() { 
/* provide your watch face implementation */ 
return new Engine(); 


/* implement service callback methods */ 
private class Engine extends CanvasWatchFaceService.Engine { 


@Override 

public void onCreate(SurfaceHolder holder) { 
super.onCreate(holder); 
/* initialize your watch face */ 


@Override 

public void onPropertiesChanged(Bundle properties) { 
super .onPropertiesChanged(properties); 
/* get device features (burn-in, low-bit ambient) */ 


@Override 

public void onTimeTick() { 
super.onTimeTick(); 
/* the time changed */ 


@Override 

public void onAmbientModeChanged(boolean inAmbientMode) { 
super .onAmbientModeChanged(inAmbientMode) ; 
/* the wearable switched between modes */ 


@Override 
public void onDraw(Canvas canvas, Rect bounds) { 
/* draw your watch face */ 


@Override 

public void onVisibilityChanged(boolean visible) { 
super.onVisibilityChanged(visible) ; 
/* the watch face became visible or invisible */ 


Note: Android SDK 里 的 WatchFace 示例 示范 了 如 何 通 过 继承 ~CanvaswatchFaceService 
类 来 实现 模拟 和 数字 表盘 。 这 个 示例 位 于 android-sdk/samples/android- 


21/wearable/WatchFace 目录 。 
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canvaswatchFaceservice 类 提供 一 个 类 似 View.invalidate()) 方法 的 销毁 机 制 。 当 我 们 想 要 系 
统 重 新 绘制 表盘 时 ， 我 们 可 以 在 实现 中 调用 invalidate() 方法 。 在 主 UI 线程 中 ， 我 们 可 以 
只 用 invalidate() 方法 。 然 后 调用 postinvalidate() 方法 从 其 它 的 的 线程 中 销毁 画布 。 


更 多 关于 实现 CanvasWatchFaceService.Engine 类 的 方法 ， 请 见 绘制 表盘 2 


WO ARRA 


实现 完 表盘 服务 之 后 ， 我 们 需要 在 可 穿戴 应 用 的 manifest 文件 中 注册 该 实现 。 当 用 户 安装 此 
应 用 时 ， 系 统 会 使 用 关于 服务 的 信息 ， 使 得 可 穿戴 设备 上 Android Wear 配套 应 用 和 表盘 选择 
器 里 的 表盘 可 用 。 


下 面 的 代码 片段 介绍 了 如 何在 application 节点 下 注册 一 个 表盘 实现 : 


«service 
android:name=".AnalogwatchFaceService" 
android: label="@string/analog_name" 
android:allowEmbedded="true" 
android: taskAffinity="" 
android:permission-"android.permission.BIND WALLPAPER" > 
«meta-data 
android:name="android.service.wallpaper" 
android: resource="@xml/watch_face" /> 
<meta-data 
android:name="com.google.android.wearable.watchface.preview" 
android: resource="@drawable/preview_analog" /> 
<meta-data 
android:name-"com.google.android.wearable.watchface.preview circular" 
android:resource-"Qdrawable/preview analog circular" /> 
<intent-filter> 
«action android:name="android.service.wallpaper.WallpaperService" /> 
«category 
android:name- 
"com.google.android.wearable.watchface.category.WATCH FACE" /» 
«/intent-filter» 


«/service» 


当 向 用 户 展示 所 有 安装 在 可 穿戴 设备 的 表盘 时 ， 设 备 上 的 Android Wear 配套 应 用 和 表盘 选择 
器 使 用 com.google.android.wearable.watchface.preview 元 数据 项 定义 的 预览 图 。 为 了 取得 这 
个 drawable， 可 以 运行 Android Wear 设备 或 者 模拟 器 上 的 表盘 并 截图 。 在 hdpi 屏幕 的 
Android Wear 设备 上 ， 预 览 图 像 一 般 是 320x320 像素 。 


圆 形 设 备 上 看 起 来 非常 不 同 的 表盘 可 以 提供 圆 形 和 方形 的 预览 图 。 使 用 
com.google.android.wearable.watchface.preview 元 数据 项 指定 一 个 圆 形 的 预览 图 。 
表盘 包含 两 种 预览 图 ， 可 穿戴 应 用 上 的 配套 应 用 和 表盘 选择 器 会 根据 手表 的 形状 选择 适合 的 


预览 图 。 如 果 没 有 包含 圆 形 的 预览 图 ， 那 么 方形 和 圆 形 的 设备 都 会 用 方形 的 预览 图 。 对 于 辆 
形 的 设备 ， 方 形 的 预览 图 会 被 一 个 圆 形 剪裁 掉 。 
android.service.wallpaper 元 数据 项 指定 包含 wallpaper 节点 的 watch_face.xml 资源 文 


件 : 


«?xml version="1.0" encoding="UTF-8"?> 
«wallpaper xmlns:android-"http://schemas.android.com/apk/res/android" /> 


我 们 的 可 穿戴 应 用 可 以 包含 多 个 表盘 。 我 们 必须 为 每 个 表盘 实现 添加 一 个 服务 节点 到 可 穿戴 
应 用 的 manifest 文件 中 。 


oe All A 


编写 :heray1990 - Æ X: http://developer.android.com/training/wearables/watch- 
faces/drawing.html 


配置 完工 程 和 添加 了 实现 表盘 服务 (watch face service) 的 类 之 后 ， 我 们 可 以 开始 编写 初始 
化 和 绘制 自 定 义 表盘 的 代码 了 。 


这 节 课 通过 Android SDK 中 的 WatchFace 示例 ， 来 介绍 系统 是 如 何 调用 表盘 服务 的 方法 。 这 
个 示例 位 于 android-sdk/samples/android-21/wearable/WatchFace 目录 。 这 里 描述 服务 实现 的 
很 多 方面 (例如 初始 化 和 检测 设备 功能 ) 可 以 应 用 到 任意 表盘 ， 所 以 我 们 可 以 重用 一 些 代码 
到 我 们 的 表盘 当中 。 





Figure 1. WatchFace 示例 中 的 模拟 和 数字 表意 


初始 化 表盘 


当 系 统 加 载 我 们 的 服务 时 ， 我 们 应 该 分 配 和 初始 化 表盘 需要 的 大 部 分 资源 ， 包 括 加 载 位 图 资 
源 、 创 建 定时 器 对 象 来 运行 自 定义 动画 、 配 置 颜 色 风 格 和 执行 其 他 运算 。 我 们 通常 只 执行 一 
次 这 些 操作 和 重用 它们 的 结果 。 这 个 习惯 可 以 提高 表盘 的 性 能 并 且 更 容易 地 维护 代码 。 
初始 化 表盘 ， 需 要 : 

1. 为 自 定义 定时 器 、 图 形 对 象 和 其 它 组 件 声明 变量 。 

2. 在 Engine.oncreate() 方法 中 初始 化 表盘 组 件 。 


3. 在 Engine.onvisibilityChanged() 方法 中 初始 化 自 定义 定时 器 。 


下 面 的 部 分 详细 介绍 了 上 述 几 个 步骤 。 


声明 变量 


当 系 统 加 载 我 们 的 服务 时 ， 我 们 初始 化 的 那些 资源 需要 在 我 们 实现 的 不 同 点 都 可 以 被 访问 ， 
所 以 我 们 可 以 重用 这 些 资源 。 我 们 可 以 通过 在 watchFaceservice.Engine 实现 中 为 这 些 资 源 声 
明成 员 变 量 来 达到 上 述 目 的 。 


为 下 面 的 组 件 声 明 变 量 : 
图 形 对 象 


大 部 分 表盘 至 少 包 含 一 个 位 图 用 于 表盘 的 背景 ， 如 创建 实施 策略 描述 的 一 样 。 我 们 可 以 使 用 
额外 的 位 图 图 像 来 表示 表盘 的 时 钟 指针 或 者 其 它 设计 元 素 。 

定时 计时 器 

当时 间 变 化 时 ， 系 统 每 隔 一 分 钟 会 通知 表盘 一 次 ， 但 一 些 表 盘 会 根据 自 定义 的 时 间 间 隔 来 运 
行动 画 。 在 这 种 情况 下 ， 我 们 需要 用 一 个 按照 所 需 频 率 计数 的 自 定义 定时 器 来 刷新 表盘 。 
时 区 变化 接收 器 

用 户 可 以 在 旅游 的 时 候 调整 时 区 ， 系 统 会 广播 这 个 事件 。 我 们 的 服务 实现 必须 注册 一 个 广播 
接收 器 ， 该 广播 接收 器 用 于 接收 时 区 改变 或 者 更 新 时 间 的 通知 。 

WatchFace 示例 中 的 AnalogwatchFaceService.Engine 类 定义 了 上 述 变量 ( 见 下面 的 代码 ) i 
自 定义 定时 器 实现 为 一 个 Handler 实例 ， 该 Handler 实例 使 用 线程 的 消息 队列 发 送 和 处 理 延 
迟 的 消息 。 对 于 这 个 特定 的 表盘 ， 自 定义 定时 器 每 秒 计数 一 次 。 当 定时 器 计数 ，handler 调用 
invalidate() 方法 ， 然 后 系统 调用 onDraw( ) 方法 重新 绘制 表盘 。 


private class Engine extends CanvasWatchFaceService.Engine { 
static final int MSG UPDATE TIME = 0; 


/* a time object */ 
Time mTime; 


/* device features */ 
boolean mLowBitAmbient; 


/* graphic objects */ 

Bitmap mBackgroundBitmap; 
Bitmap mBackgroundScaledBitmap; 
Paint mHourPaint; 

Paint mMinutePaint; 


/* handler to update the time once a second in interactive mode */ 
final Handler mUpdateTimeHandler = new Handler() { 
@Override 
public void handleMessage(Message message) { 
switch (message.what) { 
case MSG_UPDATE_TIME: 
invalidate(); 
if (shouldTimerBeRunning()) { 
long timeMs = System.currentTimeMillis(); 
long delayMs = INTERACTIVE_UPDATE_RATE_MS 
- (timeMs % INTERACTIVE_UPDATE_RATE_MS); 
mUpdateTimeHandler 
.sendEmptyMessageDelayed(MSG UPDATE TIME, delayMs); 


break; 


un 


/* receiver to update the time zone */ 
final BroadcastReceiver mTimeZoneReceiver - new BroadcastReceiver() ( 
@Override 
public void onReceive(Context context, Intent intent) { 
mTime.clear(intent.getStringExtra("time-zone")); 
mTime.setToNow(); 


}; 


/* service methods (see other sections) */ 


初始 化 表盘 组 件 


在 为 位 图 资源 、 色 彩 风格 和 其 它 每 次 重新 绘制 表 瘟 都 会 重用 的 组 件 声明 成 员 变量 之 后 ， 在 系 
统 加 载 服务 时 初始 化 这 些 组 件 。 只 初始 化 这 些 组 件 一 次 ， 然 后 重用 它们 以 提升 性 能 和 电池 使 


用 时 间 。 


在 Engine.oncreate() 方法 中 ， 初 始 化 下 面 的 组 件 : 


e 加 载 背 景 图 片 。 

e 创建 风格 和 色彩 来 绘制 图 形 对 象 。 

e 分配 一 个 对 象 来 保存 时 间 。 

e 配置 系统 Ul。 
在 AnalogwatchFaceService 类 的 Engine.onCreate() 方法 初始 化 这 些 组 件 的 代码 如 下 : 
@Override 


public void onCreate(SurfaceHolder holder) { 
super.onCreate(holder); 


/* configure the system UI (see next section) */ 


/* load the background image */ 

Resources resources - AnalogWatchFaceService.this.getResources(); 
Drawable backgroundDrawable - resources.getDrawable(R.drawable.bg); 
mBackgroundBitmap - ((BitmapDrawable) backgroundDrawable).getBitmap(); 


/* create graphic styles */ 

mHourPaint - new Paint(); 
mHourPaint.setARGB(255, 200, 200, 200); 
mHourPaint.setStrokeWidth(5.0f); 
mHourPaint.setAntiAlias(true); 
mHourPaint.setStrokeCap(Paint.Cap.ROUND); 


/* allocate an object to hold the time */ 
mTime - new Time(); 


当 系 统 初始 化 表盘 时 ， 只 会 加 载 背 景 位 图 一 次 。 图 形 风格 被 Paint 类 实例 化 。 然 后 我 们 在 
Engine.onDraw() 方法 中 使 用 这 些 风 格 来 绘制 表盘 的 组 件 ， 如 绘制 表意 描 述 的 那样 。 


初始 化 自 定义 定时 器 


作为 表盘 开发 者 ， 我 们 通过 使 定时 器 要 求 的 频率 计数 ， 来 决定 设备 在 交互 模式 时 多 久 
新 一 次 表盘 。 这 使 得 我 们 可 以 创建 自 其 它 视觉 效果 。 


Note: 在 环境 模式 下 ， 系 统 不 会 可 靠 地 调用 自 定义 定时 器 。 关 于 在 环境 模式 下 更 新 表盘 
的 内 容 ， 请 看 在 环境 模式 下 更 新 表盘 。 


在 声明 变量 部 分 介绍 了 一 个 AnalogwatchFaceservice 类 定义 的 每 秒 计 数 一 次 的 定时 器 例子 。 
在 Engine.onVisibilityChanged() 方法 里 ， 如 果 满 足 如 下 两 个 条 件 ， 则 启动 自 定义 定时 器 
e 表盘 可 见 的 。 
© 设备 处 于 交互 模式 。 
如 果 有 必要 ” AnalogwatchFaceService 会 调度 下 一 个 定时 器 进行 计数 : 
private void updateTimer() { 
mUpdateTimeHandler.removeMessages(MSG UPDATE TIME); 


if (shouldTimerBeRunning()) 1 
mUpdateTimeHandler.sendEmptyMessage(MSG UPDATE TIME); 


private boolean shouldTimerBeRunning() { 
return isVisible() && !isInAmbientMode(); 


该 自 定 义 定 时 器 每 秒 计数 一 次 ， 如 声明 变量 介绍 的 一 样 。 


在 Engine.onVisibilityChanged() 方法 中 ， 按 要 求 启 动 定时 器 并 为 时 区 的 变化 注册 接收 器 : 


@Override 
public void onVisibilityChanged(boolean visible) { 
super.onVisibilityChanged(visible) ; 


if (visible) { 
registerReceiver(); 


// Update time zone in case it changed while we weren't visible. 
mTime.clear(TimeZone.getDefault().getID()); 
mTime.setToNow(); 
} else f 
unregisterReceiver(); 


// Whether the timer should be running depends on whether we're visible and 
// whether we're in ambient mode), so we may need to start or stop the timer 
updateTimer(); 


4 RAAT IAN onvisibilitychanged() 方法 为 时 区 变化 注册 了 接收 器 ， 并 且 如 果 设 备 在 交互 
BS 


模式 ， 则 启动 自 定 义 定 时 器 。 当 表盘 不 可 见 ， 这 个 方法 停止 自 定义 定时 器 并 且 注 销 检 测 时 区 
变化 的 接收 器 。 下 面 是 registerReceiver() 和 unregisterReceiver() 方法 的 实现 : 


private void registerReceiver() { 
if (mRegisteredTimeZoneReceiver) { 
return; 


} 


mRegisteredTimeZoneReceiver = true; 
IntentFilter filter = new IntentFilter(Intent.ACTION TIMEZONE CHANGED); 
AnalogwatchFaceService.this.registerReceiver(mTimeZoneReceiver, filter); 


private void unregisterReceiver() { 
if (!mRegisteredTimeZoneReceiver) { 
return; 


} 


mRegisteredTimeZoneReceiver = false; 
AnalogwatchFaceService.this.unregisterReceiver(mTimeZoneReceiver); 
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在 环境 模式 下 ， 系 统 每 分 钟 调用 一 次 Engine.onTimeTick() 方法 。 通 常 在 这 种 模式 下 ， 每 分 
钟 更 新 一 次 表盘 已 经 足够 了 。 为 了 在 环境 模式 下 更 新 表盘 ， 我 们 必须 使 用 一 个 在 初始 化 自 
义 定时 器 介绍 的 自 定义 定时 器 。 


分 
定 


在 环境 模式 下 ， 大 部 分 表盘 实现 在 Engine.onTimeTick() 方法 中 简单 地 销毁 画布 来 重新 绘制 
RE: 
@Override 


public void onTimeTick() { 
super .onTimeTick(); 


invalidate(); 


配置 系统 UI 


表盘 不 应 该 干涉 系统 UI 组件， 在 Accommodate System UI Element 中 有 介绍 。 如 果 我 们 的 
表盘 背景 比较 亮 或 者 在 屏幕 的 底部 附近 显示 了 人 信息， 那么 我 们 可 能 要 配置 notification cards 
的 尺寸 或 者 启用 背景 保护 。 


当 表 总 在 动 的 时 候 ，Android Wear 允许 我 们 配置 系统 UI 的 下 面 几 个 方面 : 
e 指定 第 一 个 notification card 离 屏 幕 有 多 远 。 
e 指定 系统 是 否 将 时 间 绘 制 在 表盘 上 。 


e 在 环境 模式 下 ， 显 示 或 者 隐藏 notification card ° 
e 用 纯色 背景 保护 系统 指针 。 


e 指定 系统 指针 的 位 置 。 


为 了 配置 这 些 方 面 的 系统 UI， 需 要 创建 一 个 watchFacestyle 实例 并 且 将 其 传 进 
Engine.setWatchFaceStyle() 方法 。 


FW AnalogwatchFaceservice 类 配置 系统 UI 的 方法 : 


@Override 
public void onCreate(SurfaceHolder holder) { 
super.onCreate(holder); 


/* configure the system UI */ 

setWatchFaceStyle(new WatchFaceStyle.Builder(AnalogwatchFaceService.this) 
.setCcardPeekMode(WatchFaceStyle.PEEK MODE SHORT) 
.setBackgroundVisibility(WatchFaceStyle 


.BACKGROUND VISIBILITY INTERRUPTIVE) 
.setShowSystemUiTime(false) 
.build()); 


上 述 的 代码 将 card 配置 成 一 行 高 ，card 的 背景 只 会 简单 地 显示 和 只 用 于 中 断 的 notification * 
不 会 显示 系统 时 间 (因为 表盘 会 绘制 自己 的 时 间 ) 。 


我 们 可 以 在 表盘 实现 的 任意 时 刻 配 置 系 统 的 UI 风格 。 例 如 ， 如 果 用 户 选择 了 和 白色 背景 ， 我 们 
可 以 为 系统 指针 添加 背景 保护 。 


更 多 关于 配置 系统 ULNAR? HIM watchFacestyle 类 的 API 参考 文档 。 


获得 设备 屏幕 信息 


当 系 统 确定 了 设备 屏幕 的 属性 时 ， 系 统 会 调用 Engine.onPropertieschanged() 方法 ， 例 如 设 
备 是 否 使 用 低 比 特 率 的 环境 模式 和 屏幕 是 否 需要 烧毁 保护 。 


下 面 的 代码 介绍 如 何 获得 这 些 属 性 : 


@Override 
public void onPropertiesChanged(Bundle properties) { 
super.onPropertiesChanged(properties); 
mLowBitAmbient - properties.getBoolean(PROPERTY LOW BIT AMBIENT, false); 
mBurnInProtection - properties.getBoolean(PROPERTY BURN IN PROTECTION, 
false); 
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e 对 于 使 用 低 比 特 率 环境 模式 的 设备 ， 屏 幕 在 环境 模式 下 为 每 种 磊 色 提供 更 少 的 比特 ， 所 
以 当 设 备 切换 到 环境 模式 时 ， 我 们 应 该 禁用 抗 锯 浮 和 位 图 滤 镜 。 

e 对 于 要 求 烧 毁 保 护 的 设备 ， 在 环境 模式 下 避免 使 用 大 块 的 白色 像素 ， 并 且 不 要 将 内 容 放 
在 离 屏幕 边缘 10 个 像素 范围 内 ， 因 为 系统 会 周期 地 改变 内 容 以 避免 像素 烧毁 。 


更 多 关于 低 比 特 率 环境 模式 和 烧毁 保护 的 内 容 ， 请 见 Optimize for Special Screens » € 2 X 
于 如 何 禁用 位 图 滤 镜 的 内 容 ， 请 见 位 图 滤 镜 


响应 两 种 模式 间 的 变化 


当 设 备 在 环境 模式 和 交互 模式 之 间 转换 时 ， 系 统 会 调用 Engine. onAmbientModeChanged( ) 方 
法 。 我 们 的 服务 实现 应 该 对 在 两 种 模式 间 切 换 作 出 必要 的 调整 ， 然 后 调用 invalidate() 方法 
来 重新 绘制 表盘 。 


下 面 的 代码 介绍 了 这 个 方法 如 何在 WatchFace 示例 的 AnalogwatchFaceservice 类 中 实现 : 


@Override 
public void onAmbientModeChanged(boolean inAmbientMode) { 


super .onAmbientModeChanged(inAmbientMode) ; 


if (mLowBitAmbient) { 
boolean antiAlias = !inAmbientMode; 
mHourPaint.setAntiAlias(antiAlias); 
mMinutePaint.setAntiAlias(antiAlias); 
mSecondPaint.setAntiAlias(antiAlias); 
mTickPaint.setAntiAlias(antiAlias); 


} 
invalidate(); 
updateTimer(); 


这 个 例子 对 一 些 图 形 风 格 做 出 了 调整 和 销毁 画布 ， 使 得 系统 可 以 重新 绘制 表盘 。 


绘制 表盘 


绘制 自 定义 的 表盘 ， 系 统 调用 带 有 Canvas 实例 和 绘制 表盘 所 在 的 bounds 两 个 参数 的 
Engine.onDraw() 方法 。bounds 参数 说 明 任 意 内 播 的 区 域 ， 如 一 些 圆 形 设备 底部 的 “下 巴 ”。 
我 们 可 以 像 下 面 介 绍 的 一 样 来 使 用 画布 绘制 表盘 : 

1， 如 果 是 首次 调用 onpraw() 方法 ， 缩 放 背 景 来 匹配 它 。 


2. 检查 设备 处 于 环境 模式 还 是 交互 模式 。 
3. 处 理 任 何 图 形 计 算 。 


4. 在 画布 上 绘制 背景 位 图 。 
5. 使 用 Canvas 类 中 的 方法 绘制 表盘 。 


在 WatchFace 示例 中 的 AnalogwatchFaceservice 类 按照 如 下 这 些 步 骤 来 实现 onra) 方 
法 : 


@Override 

public void onDraw(Canvas canvas, Rect bounds) { 
// Update the time 
mTime.setToNow(); 


int width = bounds.width(); 
int height - bounds.height(); 


// Draw the background, scaled to fit. 
if (mBackgroundScaledBitmap -- null 
|| mBackgroundScaledBitmap.getWidth() !- width 
|| mBackgroundScaledBitmap.getHeight() !- height) ( 
mBackgroundScaledBitmap - Bitmap.createScaledBitmap(mBackgroundBitmap, 
width, height, true /* filter */); 
} 


canvas.drawBitmap(mBackgroundScaledBitmap, 9, 9, null); 


// Find the center. Ignore the window insets so that, on round watches 
// with a "chin", the watch face is centered on the entire screen, not 
// just the usable portion. 

float centerX - width / 2f; 

float centerY - height / 2f; 


// Compute rotations and lengths for the clock hands. 

float secRot - mTime.second / 30f * (float) Math.PI; 

int minutes - mTime.minute; 

float minRot - minutes / 30f * (float) Math.PI; 

float hrRot = ((mTime.hour + (minutes / 60f)) / 6f ) * (float) Math.PI; 


float secLength - centerX - 20; 
float minLength - centerX - 40; 
float hrLength - centerX - 80; 


// Only draw the second hand in interactive mode. 
if (!isInAmbientMode()) { 
float secX = (float) Math.sin(secRot) * secLength; 
float secY = (float) -Math.cos(secRot) * secLength; 
canvas.drawLine(centerX, centerY, centerX + secX, centerY + 
secY, mSecondPaint); 


// Draw the minute and hour hands. 

float minX - (float) Math.sin(minRot) * minLength; 

float minY - (float) -Math.cos(minRot) * minLength; 

canvas.drawLine(centerX, centerY, centerX + minX, centerY + minY, 
mMinutePaint); 

float hrX - (float) Math.sin(hrRot) * hrLength; 

float hrY = (float) -Math.cos(hrRot) * hrLength; 

canvas.drawLine(centerX, centerY, centerX + hrX, centerY + hrY, 
mHourPaint); 


这 个 方法 根据 现在 的 时 间 计 算 时 钟 指针 的 位 置 和 使 用 在 oncreate() 方法 中 初始 化 的 图 形 风 
格 将 时 钟 指针 绘制 在 背景 位 图 之 上 。 其 中 ， 秒 针 只 会 在 交互 模式 下 绘制 出 来 ， 环 境 模式 不 会 


显示 。 
更 多 的 关于 用 Canvas 实例 绘制 的 内 容 ， 请 见 Canvas and Drawables e 


在 Android SDK 的 WatchFace 示例 包括 附加 的 表盘 ， 我 们 可 以 用 作 如 何 实现 onpraw() 方 
法 的 例子 。 


在 表盘 上 显示 信息 


编写 :heray1990 - Æ X: http://developer.android.com/training/wearables/watch- 


faces/information.html 


为 了 显示 时 间 ，Android Wear 3€ 4-74 cards ` notifications 和 其 它 可 穿戴 应 用 的 形式 向 用 户 提 
供 相 关 的 信息 。 创 建 自 定义 表盘 不 仅 可 以 以 丰富 的 方式 显示 时 间 ， 还 可 以 在 用 户 扫 视 设备 的 
时 候 显示 相关 的 信息 。 

像 其 它 可 穿戴 应 用 一 样 ， 我 们 的 表盘 可 以 通过 可 穿戴 数据 层 API 与 可 穿戴 设备 上 的 应 用 通 

言 。 茶 些 情况 下 ， 我 们 需要 在 工程 中 的 手持 式 应 用 模块 里 创建 一 个 activity， 该 activity AZ 
联网 或 者 用 户 的 配置 文件 中 检索 数据 ， 然 后 将 数据 分 享 给 表盘 。 





Figure 1. 表盘 集成 数据 的 例子 


创建 丰富 的 体验 
在 设计 和 实现 上 下 文 感知 的 表盘 前 ， 先 回答 下 面 几 个 问题 : 


。 我 们 想 要 包含 什么 类 型 的 数据 ? 
。 我 们 可 以 从 哪里 获得 数据 ? 


e 数据 多 久 会 显著 变化 ? 
e 如 何 表 达 数 据 ， 使 得 用 户 营 一 眼 就 明白 其 中 的 意思 ? 


Android Wear 设备 通常 与 一 个 带 有 GPS 或 者 蜂窝 数 据 连 接 的 配套 设备 配对 ， 所 以 我 们 有 无 
限 的 可 能 来 整合 不 同 数据 到 表盘 中 ， 例 如 位 置 、 日 历 事 件 、 社 交 媒 体 、 图 片 、 股 票 市 场 报 
价 、 新 闻 事 件 体 育 得 分 等 等 。 然 而 ， 并 不 是 所 有 类 型 的 数据 都 适合 表盘 ， 所 以 我 们 需要 考虑 
哪 种 类 型 的 数据 与 用 户 最 相关 。 当 可 穿戴 没有 配对 的 设备 或 者 互联 网 连接 断 开 时 ， 表 盘 应 该 
优雅 地 处 理 这 些 情况 。 


Android Wear 设备 上 活动 的 表盘 是 一 个 一 直 在 运行 的 应 用 ， 所 以 我 们 必须 使 用 高 效 节能 的 方 
法 来 获取 数据 。 例 如 ， 我 们 每 隔 10 分 钟 而 不 是 每 隔 1 分 钟 去 获取 当前 的 天 气 然后 将 结果 保存 到 
本 地 。 当 设备 从 环境 模式 切换 到 交互 模式 时 ， 我 们 可 以 刷新 上 下 文 数据 。 这 是 因为 在 切换 到 
交互 模式 时 ， 用 户 很 可 能 想 营 一 眼 手 表 。 


由 于 屏幕 的 空间 有 限 ， 并 且 用 户 看 手表 也 只 是 一 次 看 一 两 秒 ， 所 以 我 们 应 该 在 表盘 上 面 将 上 
下 文 信息 归纳 起 来 。 有 时 表达 上 下 文 信息 最 好 的 方法 是 用 图 形 和 颜色 来 反应 。 人 例如， 表盘 可 
以 根据 当前 的 天 气 改 变 自 身 的 背景 图 片 。 


添加 数据 到 表 蔓 


Android SDK 中 的 WatchFace 示例 展示 了 如 何在 calendarwatchFaceservice 类 里 从 用 户 的 配 
置 文件 中 获得 日 程 数 据 ， 然 后 显示 接 下 来 的 24 小 时 有 多 少 个 会 议 。 这 个 示例 位 于 android- 
sdk/samples/android-21/wearable/WatchFace 目录 下 。 


ou have 11 meetings In 
the next 24 hours. 





Figure 2. 日 程 表盘 
按照 下 面 的 步骤 实现 包含 上 下 文 数据 的 表盘 : 


1. 提供 一 个 任务 来 检索 数据 。 
2， 创 建 一 个 自 定义 定时 器 来 周期 性 地 调用 任务 ， 或 者 当 外 部 数据 变化 时 通知 表意 服务 。 
3， 用 更 新 的 数据 重新 绘制 表盘 。 


下 面 的 内 容 详细 介绍 了 上 述 几 个 步骤 。 


提供 一 个 任务 来 检索 数据 


在 CanvasWatchFaceService.Engine 实现 里 创建 一 个 继承 AsyncTask 的 类 。 然 后 添加 用 于 接收 
我 们 感 兴趣 的 数据 的 代码 。 


"TF X calendarwatchFaceservice 类 获取 第 二 天 会 议 数量 的 代码 : 


/* Asynchronous task to load the meetings from the content provider and 
* report the number of meetings back using onMeetingsLoaded() */ 
private class LoadMeetingsTask extends AsyncTask<Void, Void, Integer» { 
@Override 
protected Integer doInBackground(Void... voids) { 
long begin = System.currentTimeMillis(); 
Uri.Builder builder = 
WearableCalendarContract.Instances.CONTENT URI.buildUpon(); 
ContentUris.appendId(builder, begin); 
ContentUris.appendId(builder, begin + DateUtils.DAY IN MILLIS); 
final Cursor cursor - getContentResolver() .query(builder.build(), 
nude cnm e CR QUT os ERE 
int numMeetings - cursor.getCount(); 
if (Log.isLoggable(TAG, Log.VERBOSE)) { 


Log.v(TAG, "Num meetings: " + numMeetings); 
} 
return numMeetings; 
} 
@Override 


protected void onPostExecute(Integer result) { 
/* get the number of meetings and set the next timer tick */ 
onMeetingsLoaded(result); 


Wearable Support 库 的 wearableCalendarContract 类 可 以 直接 存 取 配套 设备 用 户 的 日 历 事 
件 。 


当 任 务 检索 完 数 据 时 ， 我 们 的 代码 会 调用 一 个 回调 方法 。 下 面 的 内 容 详 细 介 绍 了 如 何 实现 这 
个 回调 方法 。 


更 多 关于 从 日 历 获 取 数 据 的 内 容 ， 请 参考 Calendar Provider API 指南 。 
创建 自 定义 定时 器 


我 们 可 以 实现 一 个 周期 计数 的 自 定义 定时 器 来 更 新 数据 。 calendarwatchFaceService 类 使 用 
— Handler 实例 通过 线程 的 消息 队列 来 发 送 和 处 理 延 时 的 消息 : 


private class Engine extends CanvasWatchFaceService.Engine { 


int mNumMeetings; 


private AsyncTask«Void, Void, Integer» mLoadMeetingsTask; 


/* Handler to load the meetings once a minute in interactive mode. */ 
final Handler mLoadMeetingsHandler = new Handler() { 
@Override 
public void handleMessage(Message message) { 
switch (message.what) { 
case MSG_LOAD_MEETINGS: 
cancelLoadMeetingTask(); 
mLoadMeetingsTask - new LoadMeetingsTask(); 
mLoadMeetingsTask.execute(); 
break; 


}; 


当 可 以 看 到 表盘 时 ， 这 个 方法 初始 化 了 定时 器 : 


@Override 
public void onVisibilityChanged(boolean visible) { 
super.onVisibilityChanged(visible); 
if (visible) { 
mLoadMeetingsHandler.sendEmptyMessage(MSG LOAD MEETINGS); 
} else { 
mLoadMeetingsHandler.removeMessages(MSG LOAD MEETINGS); 
cancelLoadMeetingTask(); 


En: 
o 


下 面 的 内 容 介 绍 在 onMeetingsLoaded() 方法 设置 下 一 个 定时 


用 更 新 的 数据 重新 绘制 表盘 


当 任务 检索 完 数据 时 ， 调 用 invalidate() 方法 使 得 系统 可 以 重新 绘制 表盘 。 将 数据 保存 到 
Engine 类 的 成 员 变量 ， 这 样 我 们 就 可 以 在 onpraw() 方法 中 访问 数据 。 


CalendarWatchFaceService 类 提供 一 个 回调 方 法 给 任 务 在 检索 完 日 程 数 据 后 调用 : 


private void onMeetingsLoaded(Integer result) { 

if (result != null) ( 
mNumMeetings - result; 
invalidate(); 

} 

if (isVisible()) { 
mLoadMeetingsHandler.sendEmptyMessageDelayed( 

MSG LOAD MEETINGS, LOAD MEETINGS DELAY MS); 


回调 方法 将 结果 保存 在 一 个 成 员 变 量 中 ， 销 毁 view， 和 调度 下 一 个 定时 器 再 次 运行 任务 。 


提供 配置 Activity 


编写 :heray1990 - Æ X: http://developer.android.com/training/wearables/watch- 
faces/configuration.html 


当 用 户 安装 一 个 包含 表意 的 可 穿戴 应 用 的 手持 式 应 用 时 ， 它 们 可 以 在 手持 式 设 备 上 的 Android 
Wear 配套 应 用 和 在 可 穿戴 设备 上 的 表盘 选择 器 中 使 用 。 用 户 可 以 在 配套 应 用 上 或 者 在 可 穿戴 
设备 的 表盘 选择 器 上 选择 使 用 哪个 表盘 。 

一 些 表 盘 提 供 配 置 参 数 ， 让 用 户 客 制 化 表盘 的 外 观 和 行为 。 例 如 ， 一 些 表盘 让 用 户 选择 自 定 
义 的 背景 凑 色 ， 另 一 些 表 盘 提 供 两 个 不 同时 区 的 时 间 ， 使 得 用 户 可 以 选择 感 兴 趣 的 时 区 。 


提供 配置 参数 的 表盘 让 用 户 通过 可 穿戴 应 用 的 一 个 activity、 手 持 应 用 的 一 人 activity 或 者 两 者 
的 activity 来 客 制 化 表盘 。 用 户 可 以 启动 可 穿戴 设备 上 的 可 穿戴 配置 activity， 他 们 也 可 以 局 
动 Android Wear 配套 应 用 的 配套 配置 activity 。 


Android SDK 中 WatchFace 示例 的 数字 表盘 介绍 了 如 何 实现 手持 式 和 可 穿戴 配置 activity 和 
如 何 应 配 置 变 化 而 更 新 表盘 。 这 个 示例 位 于 android-sdk/samples/android- 
21/wearable/WatchFace 目录 。 


指定 配置 activity 的 Intent 


如 果 表 盘 包 括 配 置 的 activity， 那 么 添加 下 面 的 元 数据 项 到 可 穿戴 应 用 manifest 文件 的 服务 声 
明 部 分 : 


«service 
android:name=".DigitalWatchFaceService" ... /» 
<!-- companion configuration activity --> 


«meta-data 
android:name- 
"com.google.android.wearable.watchface.companionConfigurationAction" 
android:value- 
"com.example.android.wearable.watchface.CONFIG DIGITAL" /» 
<!-- wearable configuration activity --> 
<meta-data 
android : name= 
"com.google.android.wearable.watchface.wearableConfigurationAction" 
android:value- 
"com.example.android.wearable.watchface.CONFIG DIGITAL" /» 


«/service» 


在 应 用 的 包 名 之 前 定义 这 些 元 3 Bien 的 值 。 配 置 activity 为 这 个 intent 注册 intent filters > A 
后 系统 在 用 户 想 配置 表盘 时 局 动 这 个 intent 


如 果 表 瘟 只 包括 一 个 配套 或 者 可 穿戴 配置 activity， 那 么 我 们 只 需要 包括 上 述 例子 响应 的 元 数 
据 项 。 


创建 可 穿戴 配置 activity 


可 穿戴 配置 activity 提供 了 有 限 组 表盘 客 制 化 选择 ， 这 是 因为 复杂 的 菜单 在 小 屏幕 上 很 难 导 
部。 我 们 的 可 穿戴 配置 activity 应 该 提供 二 元 选择 和 很 少 的 选项 来 客 制 化 表盘 主要 的 方面 。 


+ 


为 了 创建 一 个 可 穿戴 配置 activity， 添 加 一 个 新 的 activity 到 可 穿戴 应 用 并 且 在 可 穿戴 应 用 的 
manifest 文件 中 声明 下 面 的 intent filter : 


«activity 
android:name-z".DigitalWatchFaceWwearableConfigActivity" 
android: label="@string/digital_config_name"> 
<intent-filter> 
«action android: name= 
"com.example.android.wearable.watchface.CONFIG DIGITAL" /> 
«category android:name- 
"com.google.android.wearable.watchface.category.WEARABLE CONFIGURATION" /» 
«category android:name-"android.intent.category.DEFAULT" /» 
</intent-filter> 
</activity> 


这 个 intent filter 的 action 的 名 字 必 须 与 之 前 在 指定 配置 activity 的 Intent 49 intent 名 字 一 
样 。 


在 我 们 的 配置 activity 中 ， 构 建 一 个 简单 的 UI 为 用 户 提 供 选择 来 客 制 化 表盘 。 当 用 户 做 出 选 
择 时 ， 使 用 可 穿戴 数据 层 API 传 达 配 置 的 变化 给 表 瘟 activity 。 


更 多 详细 内 容 ， 请 见 WatchFace 示例 中 的 DigitalwatchFaceWearableConfigActivity 和 


DigitalWatchFaceUtil 类 。 


创建 配套 配置 activity 


配套 配置 activity 让 用 户 可 以 访问 全 套 表盘 客 制 化 选择 ， 这 是 因为 在 手持 式 设备 更 大 的 屏幕 
上 ， 用 户 更 加 容易 与 复杂 的 菜 ipsi 。 例 如 ， 手 持 设备 上 的 一 个 配置 activity 向 用 户 显示 复杂 
的 颜色 选择 器 ， 让 用 户 从 该 选择 器 中 选择 表盘 的 背景 颜色 。 


为 了 创建 配套 配置 activity， 添 加 一 个 新 的 activity 到 手持 应 用 并 且 在 手持 应 用 的 manifest x 
件 中 声明 下 面 的 intentfilter : 


«activity 
android:name-z".DigitalWatchFaceCompanionConfigActivity" 
android: label="@string/app_name"> 
<intent-filter> 


«action android: name= 
"com.example.android.wearable.watchface.CONFIG DIGITAL" /> 


«category android:name- 
"com.google.android.wearable.watchface.category.COMPANION CONFIGURATION" /» 


«category android:name-"android.intent.category.DEFAULT" /» 
</intent-filter> 


</activity> 


在 我 们 的 配置 activity 中 ， 构 建 一 个 UI 为 用 户 提 供 选项 来 客 制 化 表盘 所 有 的 可 配置 组 件 。 当 
用 户 做 出 选择 时 ， 使 用 可 穿戴 数据 层 API 传 达 配 置 的 变化 给 表意 activity ° 


更 多 详细 内 容 ， 请 见 WatchFace 示例 中 的 pigitalwatchFaceCompanionConfigActivity 类 。 


在 可 穿戴 应 用 中 创建 一 个 监听 器 服务 


为 了 接收 配置 activity 中 已 更 新 的 配置 参数 ， 需 要 在 可 穿戴 应 用 创建 一 个 服务 来 实现 可 穿戴 数 
据 层 API 的 wearableListenerservice 接口 。 我 们 的 表盘 实现 可 以 在 配置 参数 改变 时 重新 绘 


制 表盘 。 


更 多 详细 内 容 ， 请 见 WatchFace 示例 的 pigitalwatchFaceConfigListenerService 和 


DigitalWatchFaceService 类 。 


定位 第 见 的 问题 


编写 :heray1990 - Æ X: http://developer.android.com/training/wearables/watch- 
faces/issues.html 
创建 Android Wear 的 客 制 化 表盘 与 创建 notification 和 可 穿戴 特有 的 activity 的 方法 不 同 。 这 
几 课 介绍 如 何 解决 我 们 在 实现 第 一 个 表盘 时 会 遇 到 的 一 些 问题 。 


检测 屏幕 的 形状 


一 些 Android Wear 设备 的 屏幕 是 方形 的 ， 另 一 些 是 圆 形 的 。 圆 形 屏幕 的 设备 可 以 在 屏幕 的 底 
部 包含 一 个 插入 部 分 (RAF SB’) 。 我 们 的 表 瘟 应 该 适应 和 利用 好 屏幕 特定 的 形状 ， 如 设 


计 指 南 中 的 描述 。 
Android Wear 让 表盘 在 运行 时 决定 屏幕 的 形状 。 为 了 检测 屏幕 是 方形 还 是 圆 形 ， 需 要 像 下 面 


的 代码 一 样 重 写 CanvasWatchFaceService.Engine 类 的 onApplyWindowInsets() 方法 : 


private class Engine extends CanvasWatchFaceService.Engine { 
boolean mIsRound; 
int mChinSize; 


@Override 

public void onApplyWindowInsets(WindowInsets insets) { 
super.onApplyWindowInsets(insets); 
mIsRound - insets.isRound(); 
mChinSize = insets.getSystemwindowInsetBottom(); 


当 重 新 给 会 制 表盘 时 ， 检查 成 员 变量 mIsRound 和 mChinSize 的 值 来 适 应 我 们 的 设计 。 


容纳 Card 


当 用 户 接 收 到 一 个 notification > notification card 可 能 会 遮盖 屏幕 很 大 一 部 分 ， 这 取决 于 系统 
Ul 的 风格 。 表 瘟 应 该 适应 这 些 情况 ， 确 保 当 notification card 出 现时 用 户 仍然 可 以 看 到 时 间 。 


4 notification card 出 现时 ， 模 拟 表盘 需要 调整 ， 如 缩小 表盘 使 得 自身 不 被 card o RF 
表盘 在 屏幕 显示 时 间 的 区 域 不 会 被 card 履 盖 ， 通 常 不 需要 作出 调整 。 使 用 
WatchFaceService.getPeekCardPosition() 方法 确定 在 card 上 方 可 用 于 调整 表盘 的 空间 。 


— Debugging 9i 
Ot 


2 ` 
Figure 1. 5 notification card 出 现时 ， 一 些 模拟 表盘 需要 调整 


p ' card 的 背景 是 透明 的 。 如 果 我 们 的 表盘 在 环境 模式 下 ，card 的 附近 包含 详细 
的 信息 么 可 以 考虑 在 card 的 上 面 绘制 一 个 黑色 方块 ， 确 保 用 户 可 以 读 到 card 的 内 容 。 


置 系统 图 标 


为 了 确保 系统 指示 图 标 一 直 可 见 ， 当 创建 一 个 watchFacestyle 实例 时 ， 我 们 可 以 将 配置 系统 
指示 图 标 在 屏幕 的 位 置 和 决定 是 否 需 要 背景 保护 : 


e 使 用 setstatusBarGravity() 方法 设置 状态 栏 的 位 置 。 

e 使 用 setHotwordIndicatorGravity() 方法 设置 热 词 的 位 置 。 

e 使 用 setviewProtection() 方法 ， 用 一 个 灰色 的 半 透 明 背景 保护 状态 栏 和 热 词 。 由 于 系 
统 指 示 图 标 是 白色 的 ， 如 果 我 们 的 表盘 背景 是 明亮 的 ， 这 样 做 事 很 作 要 的 。 





Figure 2. 状态 栏 
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更 多 关于 系统 指示 图 标的 内 容 ， 请 查看 配置 系统 UI 和 设计 指南 。 


使 用 相对 尺寸 


不 同 厂商 的 Android Wear 设备 屏幕 会 有 不 同 的 尺寸 和 分 辩 举 。 我 们 的 表盘 应 该 通过 使 用 相对 
尺寸 而 不 是 绝对 像素 值 来 适应 这 些 差 异 。 

当 我 们 绘制 表盘 时 ， 用 Canvas.getWidth()) 和 Canvas.getHeight()) 方法 获得 画布 的 尺寸 ， 然 
后 以 屏幕 尺寸 一 部 分 所 占 比 例 的 值 来 设置 图 片 的 位 置 。 如 果 重 新 绘制 表盘 的 组 件 来 响应 
card， 那 么 根据 屏幕 里 card 上 方 剩 下 空间 所 占 比 例 的 值 来 重新 绘制 表盘 。 


优化 性 能 和 电池 使 用 时 间 


编写 :heray1990 - Æ X: http://developer.android.com/training/wearables/watch- 
faces/performance.html 


除了 有 好 的 notification cards 和 系统 指示 图 标 之 外 ， 我 们 还 需要 确保 表盘 的 动画 运行 流畅 ， 
服务 不 会 执行 没 必 要 的 计算 。Android Wear 的 表盘 会 在 设备 上 一 直 运 行 ， 所 以 表盘 高 效 地 使 
用 电池 显得 十 分 重要 。 


这 节 课 提供 了 一 些 提示 来 加 快 动画 的 速度 ， 测 量 和 节省 设备 上 的 电量 。 


减 小 位 图 资源 的 尺寸 


很 多 表盘 由 一 张 背 景 图 片 及 其 它 被 转换 和 和 覆盖 在 背景 图 片上 面 的 图 形 资源 组 成 ， 例 如 时 钟 指 
针 和 其 它 随 着 时 间 移 动 的 设计 组 件 。 没 词 系 统 重新 绘制 表盘 的 时 候 ， 在 Engine.onpraw() 方 
法 里 面 ， 这 些 图 像 组 件 往往 会 旋转 (有 了 时 会 缩放 ) ， 详 见 绘制 表盘 。 


这 些 图 形 资 源 越 大 ， 转 换 它 们 所 需 的 运算 量 就 越 大 。 在 Engine.onpraw() 方法 中 转换 大 的 图 
形 资 源 会 大 大 地 减低 系统 运行 动画 的 帧 率 。 


了 提升 表盘 的 性 能 ， 我 们 需要 : 


e. 不 要 使 用 比 我 们 需要 的 更 大 的 图 像 组 件 。 
。 删除 边缘 周围 多 出 来 的 延明 像素 。 


在 Figure 1 中 的 时 钟 指针 例子 可 以 将 大 小 减 小 97% 。 





= 





Figure 1. 可 以 剪裁 多 余 像素 的 时 钟 指针 
这 节 内 容 介绍 的 减 小 位 图 资源 的 大 小 不 仅 提升 了 动画 的 性 能 ， 也 节省 了 电量 。 


优化 性 能 和 电池 使 用 时 间 


合并 位 图 资源 


如 果 我 们 有 经 常 需 要 一 起 绘制 的 位 图 ， 那 么 可 以 考虑 将 它们 合并 到 同一 个 图 形 资 源 中 。 在 交 
互 模式 下 ， 通 常 我 们 可 以 将 背景 图 片 和 计数 标记 组 合 起 来 ， 从 而 避免 没 词 系统 重新 绘制 表 瘟 
时 ， 都 去 绘制 两 个 全 屏 的 位 图 。 


当 绘 制 可 缩放 的 位 图 时 禁用 有 反 锯 次 功能 


当 使 用 Canvas.drawBitmap() 方法 绘制 可 缩放 的 位 图 ， 我 们 可 以 使 用 Paint 实例 去 设置 一 些 
选项 。 为 了 提升 性 能 ， 使 用 setAntiAlias()) 方法 禁用 反 锯 上 当 ， 这 是 由 于 这 个 设置 对 于 位 图 没有 
任何 影响 © 


使 用 位 图 滤 镜 


对 于 绘制 在 其 它 组 件 上 的 位 图 资源 ， 可 以 在 同一 个 Paint 实例 上 使 用 setFilterBitmap()) 方法 
来 打开 位 图 滤 镜 。Figure 2 显示 了 使 用 和 没 使 用 位 图 滤 镜 的 放大 的 时 钟 指针 。 


» | 全 





Figure 2. 没 使 用 位 图 滤 镜 ( 左 ) 和 使 用 位 图 滤 镜 ( 右 ) 


Note: 在 低 比 特 率 的 环境 模式 下 ， 系 统 不 能 可 靠 地 泻 染 图 片 的 颜色 ， 从 而 不 能 保证 成 功 
地 执行 位 图 滤 镜 。 因 此 ， 在 环境 模式 下 ， 禁 用 位 图 滤 镜 。 


和 复杂 的 操作 移 到 onDraw() 方法 外 面 


每 次 重新 绘制 表盘 时 ， 系 统 会 调用 Engine.onpraw() 方法 ， 所 以 为 了 提升 性 能 ， 我 们 应 该 只 
将 用 于 更 新 表盘 的 重要 的 操作 放 到 这 个 方法 中 。 


可 以 的 话 ， 避 免 在 ondraw() 方法 里 处 理 下 面 这 些 操作 : 
e 加 载 图 片 和 其 它 资源 。 
e 调整 图 片 的 大 小 。 
e TRIZ 

运行 在 帧 与 帧 之 间 不 会 改变 的 计算 。 
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通常 可 以 在 Engine.onCreate() 方法 中 运行 上 述 这 些 操 作 。 我 们 可 以 在 执 
行 Engine.onSurfaceChanged() 方法 之 前 调整 图 片 大 小 。 其 中 ， 该 方法 提供 了 画布 的 大 小 。 


为 了 分 析 表 盘 的 性 能 ， 我 们 可 以 使 用 Android Device Monitor。 特 别 地 ， 确 保 
Engine.onDraw() 实现 的 运行 时 间 是 短 的 和 调用 是 一 致 的 。 详 细 内 容 见 使 用 DDMS © 


a > 
Y f AJ x dE MCA 
除了 前 面部 分 介绍 的 技术 之 外 ， 我 们 还 需要 按照 下 面 的 最 佳 做 法 来 降低 表盘 的 电量 消耗 。 


降低 动画 的 帧 频 

动画 通常 需要 消耗 大 量 计算 资源 和 电量 。 大 部 分 动画 在 每 秒 30 帧 的 情况 下 看 上 去 是 流畅 的 ， 
所 以 我 们 应 该 加 免 动画 的 帧 频 比 每 秒 30 帧 高 。 

让 CPU 睡眠 


表意 的 动画 和 内 容 的 小 变化 会 唤醒 CPU。 表盘 应 该 在 动画 之 间 让 CPU 睡眠 。 例 如 ， 在 交互 
模式 下 ， 我 们 可 以 每 隔 一 秒 使 用 动画 的 短 脉冲 ， 然 后 在 下 一 秒 让 CPU 睡眠 。 频 繁 地 让 CPU 
睡眠 ， 甚 至 短暂 地 ， 都 可 以 有 效 地 降低 电量 消耗 。 


为 了 最 大 化 电池 使 用 时 间 ， 谨 懂 地 使 用 动画 。 即 使 闪烁 动画 在 闪烁 的 时 候 也 会 唤醒 CPU 并 且 
消耗 电量 。 

监控 电量 消耗 

在 Android Wear companion app 的 Settings > Watch battery 下 ， 开 发 者 和 用 户 可 以 看 到 
可 穿戴 设备 中 不 同 进程 还 有 多 少 电量 。 


在 Android 5.0 中 ， 更 多 关于 提升 电池 使 用 时 间 的 信息 ， 请 见 Project Volta 。 


Android Wear 上 的 位 置 检测 


编写 :heray1990 - Æ X: http;//developer.android.com/training/articles/wear-location- 
detection.html 


可 穿戴 设备 上 的 位 置 感知 让 我 们 可 以 创建 为 用 户 提供 更 好 地 了 解 地 理 位 置 、 移 动 和 周围 事物 
的 应 用 。 由 于 可 穿戴 设备 小 型 和 方便 的 特点 ， 我 们 可 以 构建 低 摩擦 应 用 来 记录 和 响应 位 置 数 
据 。 


一 些 可 穿戴 设备 带 有 GPS 感应 器 ， 它 们 可 以 在 不 需要 其 它 设备 的 帮助 下 检索 位 置 数据 。 无 论 
如 何 ， 当 我 们 在 可 穿戴 应 用 上 请 求 获取 位 置 数据 ， 我 们 不 需要 担心 位 置 数据 从 哪里 发 出 ; 系 
统 会 用 最 节能 的 方法 来 检索 位 置 更 新 。 我 们 的 应 用 应 该 可 以 处 理 位 置 数据 的 丢失 ， 以 防 没有 
^E GPS 感应 器 的 可 穿戴 设备 与 配套 设备 断 开 和 连接。 


这 篇 文章 介绍 如 何 检 查 设备 上 的 位 置 感应 器 、 检 索 位 置 数 据 和 监视 数据 连接 。 


Note: 这 篇 文章 假设 我 们 知道 如 何 使 用 Google Play services API 来 检索 位 置 数据 。 更 多 
相关 的 内 容 ， 请 见 Android 位 置信 息 。 


连接 Google Play Services 


可 穿戴 设备 上 的 位 置 数据 可 以 通过 Google Play services location APIs 来 获取 。 我 们 可 以 使 
用 FusedLocationProviderApi 和 它 伴随 的 类 来 获取 这 个 数据 。 为 了 访问 位 置 服务 ， 可 以 创建 
GoogleApiClient 实例 ， 这 个 实例 是 任何 Google Play services APIs 的 主要 入 口 。 


Caution: 不 要 使 用 Android 框架 已 有 的 Location APls。 检 索 位 置 更 新 最 好 的 方法 是 通过 
这 篇 文章 介绍 的 Google Play services API 获取 。 


为 了 连接 Google Play services， 配 置 应 用 来 创建 GoogleApiClient 实例 : 


1. 创建 一 个 activity 来 指定 ConnectionCallbacks » OnConnectionFailedListener 和 
LocationListener 接口 的 实现 。 

2. 在 activity 的 onCreate()) 方法 中 ， 创 建 GoogleApiClient 实例 和 添加 位 置 服务 。 

3. 为 了 优雅 地 管理 连接 的 生命 周期 ， 在 onResume()) 方法 里 调用 connect()) 和 在 
onPause()) 方法 里 调用 disconnect())。 


下 面 的 代码 示例 介绍 了 一 个 activity 的 实现 来 实现 LocationListener 接口 : 


public class WearableMainActivity extends Activity implements 
GoogleApiClient.ConnectionCallbacks, 
GoogleApiClient.OnConnectionFailedListener, 
LocationListener { 


private GoogleApiClient mGoogleApiClient; 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState) ; 


mGoogleApiClient = new GoogleApiClient.Builder(this) 
.addApi(LocationServices.API) 
.addApi(Wearable.API) // used for data layer API 
.addConnectionCallbacks(this) 
.addOnConnectionFailedListener(this) 
.build(); 


@Override 

protected void onResume() { 
super.onResume(); 
mGoogleApiClient.connect(); 


@Override 
protected void onPause() { 
super .onPause(); 


mGoogleApiClient.disconnect(); 


更 多 关于 连接 Google Play services 的 内 容 ， 请 见 Accessing Google APIs ° 


请 求 位 置 更 新 
应 用 连接 到 Google Play services API 之 后 ， 它 已 经 准备 好 开始 接收 位 置 更 新 了 。 当 系统 为 我 
们 的 客户 端 调用 onConnected()) 回调 函数 时 ， 我 们 可 以 按照 下 面 的 步骤 构建 位 置 更 新 请 求 : 


1. 创建 一 个 LocationRequest 对 象 并 且 用 像 setPriority()) 这 样 的 方法 设置 选项 。 
2. 使 用 requestLocationUpdates() 请 求 位 置 更 新 。 
3. 在 onPause() 方法 里 使 用 removeLocationUpdates() 删除 位 置 更 新 。 


下 面 的 例子 介绍 了 如 何 接收 和 删除 位 置 更 新 : 


@Override 
public void onConnected(Bundle bundle) { 

LocationRequest locationRequest = LocationRequest.create() 
.setPriority(LocationRequest.PRIORITY HIGH ACCURACY) 
.setInterval(UPDATE INTERVAL MS) 
.setFastestInterval(FASTEST INTERVAL MS); 


LocationServices.FusedLocationApi 
.requestLocationUpdates(mGoogleApiClient, locationRequest, this) 
.setResultCallback(new ResultCallback() { 


@Override 
public void onResult(Status status) { 
if (status.getStatus().isSuccess()) { 
if (Log.isLoggable(TAG, Log.DEBUG)) { 
Log.d(TAG, "Successfully requested location updates"); 
} 
} else { 
Log.e(TAG, 
"Failed in requesting location updates, " 
+ "status code: " 
+ status.getStatusCode() 
+ ", message: " 
+ status.getStatusMessage()); 


3); 


@Override 
protected void onPause() { 
super .onPause(); 
if (mGoogleApiClient.isConnected()) { 
LocationServices.FusedLocationApi 
. removeLocationUpdates(mGoogleApiClient, this); 


} 
mGoogleApiClient.disconnect(); 
} 
@Override 


public void onConnectionSuspended(int i) { 
if (Log.isLoggable(TAG, Log.DEBUG)) { 
Log.d(TAG, "connection to location client suspended"); 


至 此 ， 我 们 已 经 打开 了 位 置 更 新 ， 系 统 调 用 onLocationChanged()) 方法 ， 同 时 按照 
setlnterval()) 指定 的 时 间 间 隔 更 新 位 置 。 


检测 设备 上 的 GPS 


不 是 所 有 的 可 穿戴 设备 都 有 GPS 感应 器 。 如 果 用 户 出 去 外 面 并 且 将 他 们 的 手机 放 在 家 里 ， 那 
么 我 们 的 可 穿戴 应 用 无 法 通过 一 个 绑 定 连接 来 接收 位 置 数据 。 如 果 可 穿戴 设备 没有 GPS 感应 
器 ， 那 么 我 们 应 该 检测 到 这 种 情况 并 且 警 告 用 户 位 置 功 能 不 可 用 。 


使 用 hasSystemFeature()) 方法 确定 Android Wear 设备 是 否 有 内 置 的 GPS 感应 器 。 下 面 的 
代码 用 于 当 我 们 启动 一 个 activity 时 ， 检 测 设 备 是 否 有 内 置 的 GPS 感应 器 : 


protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


setContentView(R.layout.main activity); 

if (!thasGps()) { 
Log.d(TAG, "This hardware doesn't have GPS."); 
// Fall back to functionality that does not use location or 
// warn the user that location function is not available. 


} 


private boolean hasGps() { 
return getPackageManager().hasSystemFeature(PackageManager .FEATURE_LOCATION_GPS); 


} 


处 理 断 开 事 件 


可 穿戴 设备 在 回答 绑 定 连接 位 置 数据 时 可 能 会 突然 断 开 连接 。 如 果 我 们 的 可 穿戴 应 用 期 待 持 
续 的 数据 ， 那 么 我 们 必须 处 理 数据 中 断 或 者 不 可 用 的 断 线 问 题 。 在 一 个 不 带 有 GPS 感应 器 的 
可 穿戴 设备 上 ， 当 设备 与 绑 定 数据 连接 断 开 时 ， 位 置 数据 会 丢失 。 


以 防 基于 绑 定 位 置 数据 连接 的 应 用 和 可 穿戴 设备 没有 GPS 感应 器 ， 我 们 应 该 检测 连接 的 断 
线 ， 警 告 用 户 和 优雅 地 降低 应 用 的 功能 。 
为 了 检测 数据 连接 的 断 线 : 

1. 继承 WearableListenerService 来 监听 重要 的 数据 层 事 件 。 


2. Æ Android manifest 文件 中 声明 一 个 intent filter 来 把 WearableListenerService 通知 给 系 
A, » ik ^ filter 允许 系统 按 需 绑 定 我 们 的 服务 。 


«service android:name=".NodeListenerService"> 
«intent-filter» 

«action android:name-"com.google.android.gms.wearable.BIND LISTENER" /> 
</intent-filter> 


</service> 


3. ŽI onPeerDisconnected()) 方法 并 处 理 设备 是 否 有 内 置 GPS 的 情况 。 


public class NodeListenerService extends WearableListenerService { 
private static final String TAG - "NodeListenerService"; 
@Override 
public void onPeerDisconnected(Node peer) { 
Log.d(TAG, "You have been disconnected."); 
if(!hasGPS()) { 


// Notify user to bring tethered handset 
// Fall back to functionality that does not use location 


更 多 相关 的 信息 ， 请 见 监听 数据 层 事 件 指南 。 


处 理 找 不 到 位 置 的 情况 
当 GPS 信号 丢失 了 ， 我 们 仍然 可 以 使 用 getLastLocation()) 检索 最 后 可 知 位 置 。 这 个 方法 在 
我 们 无 法 修复 GPS 连接 或 者 设备 没有 内 置 GPS 并 且 断 开 与 手机 连接 的 情况 下 很 有 用 。 


下 面 的 代码 使 用 getLastLocation()) 检索 最 后 可 知 位 置 : 


Location location = LocationServices.FusedLocationApi 
.getLastLocation(mGoogleApiClient); 


同步 数据 
如 果 可 穿戴 应 用 使 用 内 置 GPS 记录 数据 ， 那 么 我 们 可 能 想 要 与 手持 应 用 同步 位 置 数据 。 对 于 
LocationListener， 我 们 可 以 实现 onLocationChanged()) 方法 来 检测 和 记录 它 改变 的 位 置 。 


下 面 的 可 穿戴 应 用 代码 检测 位 置 变化 和 使 用 数据 层 APT 来 保存 用 于 手机 应 用 日 后 检索 的 数 
据 : 


@Override 
public void onLocationChanged(Location location) { 


addLocationEntry(location.getLatitude(), location.getLongitude()); 


} 
private void addLocationEntry(double latitude, double longitude) { 
if (!mSaveGpsLocation || !mGoogleApiClient.isConnected()) { 
return 
} 


mCalendar.setTimeInMillis(System.currentTimeMillis()); 


// Set the path of the data map 
String path = Constants.PATH + "/" + mCalendar.getTimeInMillis(); 
PutDataMapRequest putDataMapRequest - PutDataMapRequest.create(path); 


// Set the location values in the data map 
putDataMapRequest.getDataMap( ) 

.putDouble(Constants.KEY LATITUDE, latitude); 
putDataMapRequest.getDataMap( ) 

.putDouble(Constants.KEY LONGITUDE, longitude); 
putDataMapRequest.getDataMap( ) 

.putLong(Constants.KEY TIME, mCalendar.getTimeInMillis()); 


// Prepare the data map for the request 
PutDataRequest request - putDataMapRequest.asPutDataRequest(); 


// Request the system to create the data item 
Wearable.DataApi.putDataltem(mGoogleApiClient, request) 
.setResultCallback(new ResultCallback() { 
@Override 
public void onResult(DataApi.DataItemResult dataItemResult) { 
if (!dataItemResult.getStatus().isSuccess()) { 
Log.e(TAG, "Failed to set the data, " 
+ "status: " + dataItemResult.getStatus() 
.getStatusCode()); 


3) 


更 多 关于 如 何 使 用 数据 层 API 的 内 容 ， 请 见 发 送 与 同步 数据 指南 。 


Android TV 应 用 


创建 TV 应 用 


编写 :applepyarc - 原文 :http://developer.android.com/training/tv/index.html 
以 下 课程 将 教授 如 何 为 TV 设备 开发 应 用 。 


Note : 如 何在 Google Play 发 布 你 的 TV 应 用 ， 详 细 请 参考 Distributing to Android TV。 
创建 TV 应 用 
如 何 开发 TV 应 用 和 移植 已 有 应 用 到 TV 设备 。 
创建 TV 播放 应 用 
如 何 开发 提供 媒体 目录 和 播放 内 容 的 应 用 。 
帮助 用 户 在 TV 上 找到 内 容 
如 何 帮 助 用 户 从 你 的 应 用 发 现 所 需 内容 。 
创建 TV 游戏 应 用 
如 何 开发 TV 游戏 。 
创建 TV 直播 应 用 
如 何 开发 TV 直播 应 用 。 
TV 应 用 清单 


TV 应 用 的 需求 清单 
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创建 TV 应 用 


编写 :applepyarc - 原文 :http://developer.android.com/training/tv/start/index.html 
e Android 5.0(API 21) 或 以 上 


Android 提 供 丰 富 的 用 户 体 验 ， 优 化 应 用 运行 于 诸如 高 清 电视 等 大 屏幕 设备 。TV 应 用 有 机 会 为 
沙发 上 的 用 户 提 供 愉 快 的 体验 。 


TV 应 用 使 用 与 手机 或 平板 应 用 相同 的 架构 。 这 意味 着 你 可 以 基于 已 知 的 Android 应 用 开发 来 创 
建新 的 TV 应 用 。 或 者 移植 已 有 的 应 用 到 TV 设备 上 上。 但是， 在 UI 上 ，TV 和 手机 或 平板 大 不 相 

同 。 为 了 使 应 用 顺畅 地 运行 在 TV 设备 上 ， 我 们 必须 设计 能 够 在 即使 3 米 之 外 也 易于 理解 的 新 界 
面 ， 提 供 可 以 使 用 方向 键 和 选择 键 操 作 的 导航 界面 。 


以 下 课程 描述 了 如 何 开始 创建 TV 应 用 ， 和 包括 设 置 开 发 环境 ， 界 面 及 导航 的 基本 要 求 ， 以 及 如 
何 处 理 TV 设 备 通 常 不 具备 的 硬件 特性 。 


Note: 鼓励 使 用 Android Studio 创 建 TV 应 用 ， 因 为 它 提 供 了 创建 项 目的 步骤 ， 库 包含 和 快 
捷 打 包 。 本 课程 假设 你 正在 使 用 Android Studio ° 


课程 
e 创建 TV 应 用 的 第 一 步 


学 习 如 何 为 TV 应 用 创建 一 个 新 的 Android Studio 项 目 或 者 修改 已 有 的 应 用 运行 到 TV 设备 
上 。 


e 处 理 TV 硬 件 

学 习 如 何 检查 应 用 是 否 运行 在 TV 硬件 上 ， 处 理 不 支持 的 硬件 特性 和 管理 控制 器 设备 。 
e 创建 TV 布局 

学 习 TV 界 面 的 最 小 要 求 及 其 实现 。 
e 创建 TV 导航 


学 习 TV 导 航 的 最 小 要 求 以 及 如 何 实现 TV 兼容 的 导航 。 


创建 TV 应 用 的 第 一 步 > 


创建 TV 应 用 
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创 | 


建 TV 应 用 的 第 一 步 


编写 :awong1900 - 原文 :http://developer.android.com/training/tv/start/start.html 


TV 应 用 使 用 与 手机 和 平板 同样 的 架构 。 这 种 相似 性 意味 着 我 们 可 以 修改 现 有 的 应 用 到 TV 设备 
或 者 用 以 前 安 草 应 用 的 经 验 开 发 TV 应 用 。 


Important: 想 把 Android TV 应 用 放 在 Google Play 中 应 满足 一 些 特 定 要 求 。 更 多 信息 , 参 
考 TV App Quality 中 的 要 求 列表 。 


本 课程 介绍 如 何 准 备 TV 应 用 开发 环境 ,和 使 应 用 能 够 运行 在 TV 设备 上 的 最 低 要 求 。 


查 明 支持 的 媒体 格式 


查看 以 下 文档 信息 ， 包 括 代码 ， 协 议和 Android TV 支持 的 格式 。 


支持 的 媒体 格式 

DRM 

android.drm 

ExoPlayer 
android.media.MediaPlay 


查 明 支持 的 媒体 格式 


查看 一 下 文档 关于 代码 ， 协 议和 Android TV 支持 的 格式 。 


支持 的 媒体 格式 

DRM 

android.drm 

ExoPlayer 
android.media.MediaPlay 


创建 TV 项 目 


本 节 讨 论 如 何 修改 已 有 的 应 用 或 者 新 建 一 个 应 用 使 之 能 够 运行 在 电视 设备 上 。 在 TV 设备 上 运 
行 的 应 用 必须 使 用 这 些 主要 组 件 : 


Activity for TV (5:751) - 在 您 的 application manifest}, 声明 一 个 可 在 TV 设备 上 运行 的 
activity。 


e TV Support Libraries (可 选 ) - 这 些 支持 库 Support Libraries 可 以 提供 搭建 TV 用 户 界 面 的 
控件 。 


前 提 条 件 
在 创建 TV 应 用 前 , 必须 做 以 下 事情 : 
e 更 新 SDK tools 到 版 本 24.0.0 或 更 高 更 新 的 SDK 工 具 能 确保 编译 和 测试 TV 应 用 
e 更 新 SDK 为 Android 5.0 (API 21) 或 更 高 更 新 的 平台 版 本 为 TV 应 用 提供 更 新 的 API 


e 创建 或 更 新 应 用 工程 为 了 支持 TV 新 APl, 我 们 必须 创建 一 个 新 工程 或 者 修改 原 工 程 的 目标 
平台 为 Android 5.0 (API 版 本 21) 或 者 更 高 。 


声明 一 个 TV Activity 


一 个 应 用 想 要 运行 在 TV 设备 中 ， 必 须 在 它 的 manifest 中 定义 一 个 启动 activity， 用 intent filter € 
含 CATEGORY LEANBACK LAUNCHER。 这 个 filter 表 明 你 的 应 用 是 在 TV 上 可 用 ， 并 且 为 
Google Play 上 发 布 TV 应 用 所 必须 。 定 义 这 个 intent 也 意味 着 点 击 主屏 幕 的 应 用 图 标 时 ， 就 是 
打开 的 这 个 activity 。 


接 下 来 的 代码 片段 显示 如 何在 manifest 中 包含 这 个 intent filter : 


<application 
android:banner="@drawable/banner" > 


<activity 
android:name-"com.example.android.MainActivity" 
android:label-"Qstring/app name" > 


<intent-filter> 
<action android:name="android.intent.action.MAIN" /> 
<category android:name="android.intent.category.LAUNCHER" /> 
</intent-filter> 
</activity> 


<activity 
android:name="com.example.android.TvActivity" 
android: label="@string/app_name" 
android: theme="@style/Theme.Leanback"> 


<intent-filter> 
<action android:name="android.intent.action.MAIN" /> 
<category android:name="android.intent.category.LEANBACK_LAUNCHER" /> 


</intent-filter> 


</activity> 
</application> 


例子 中 第 二 个 activity manifest 定 义 的 activity 是 TV 设备 中 的 一 个 启动 入 口 。 


Caution : 如 果 在 你 的 应 用 中 不 包含 CATEGORY_LEANBACK_LAUNCHER intent 
filter， 它 不 会 出 现在 TV 设备 的 Google Play 商 店 中 。 并 且 ， 即 使 你 把 不 包含 此 filter 的 应 用 
用 开发 工具 装载 到 TV 设备 中 ， 应 用 仍然 不 会 出 现在 TV 用 户 界 面 上 。 


如 果 你 正在 为 TV 设备 修改 现 有 的 应 用 ， 就 不 应 该 与 手机 和 平板 用 同样 的 activity 布 局 。TV 的 用 
PRE (或 者 现 有 应 用 的 TV 部 分 ) 应 该 提供 一 个 更 简单 的 界面 ， 更 容易 坐 在 沙发 上 用 透 控 器 

操作 。TV 应 用 设计 指南 ， 参 考 TV Design 指 导 。 查 看 TV 界面 布局 的 最 低 要 求 ， 参 考 : Building 
TV Layouts ° 


P A Leanback X 4 


Android TV 需要 你 的 应 用 使 用 Leanback 用 户 界 面 。 如 果 你 正在 开发 一 个 运行 在 移动 设备 ( 手 
机 ， 可 穿戴 ， 平 板 等 等 ) 也 包括 TV 的 应 用 ， 设 置 required 属性 为 false 。 因 为 如 果 设 置 
为 true ， 你 的 应 用 将 仅 能 运行 在 用 Leanback UI 的 设备 上 。 


«manifest» 
«uses-feature android:name="android.software. leanback" 
android: required="false" /> 


</manifest> 


声明 不 需要 触 屏 


运行 在 TV 设备 上 的 应 用 不 依靠 触 屏 去 输入 。 为 了 清楚 表明 这 一 点 ，TV 应 用 的 manifest 必 须 声 
明 android.hardware.touchscreen 为 不 需要 。 这 个 设置 表明 应 用 外 E 够 工作 在 TV 设备 上 á 并 且 也 
是 Google Play 认定 你 的 应 用 为 TV 应 用 的 要 求 。 接 下 来 的 示例 代码 展示 这 个 manifest 声 明 : 


«manifest» 
«uses-feature android:name-z"android.hardware.touchscreen" 
android:required-"false" /> 

«/manifest» 

Caution : 必须 在 manifest 中 声明 触 屏 是 不 需要 的 ， 否 则 应 用 不 会 出 现在 TV 设备 的 
Google Play 商 店 中 。 
日 ` - + 一 

提供 一 个 主屏 幕 横 幅 


如 果 应 用 包含 一 个 Leanback 的 intent filter， 它 必须 提供 每 个 语言 的 主屏 幕 横幅 。 横 幅 是 出 现 
在 应 用 和 游戏 栏 的 主屏 的 启动 点 。 在 manifest 中 这 样 描述 横幅 : 


«application 


android: banner="@drawable/banner" > 


</application> 


在 application 中 添加 android:banner 属性 为 所 有 的 应 用 activity 提 供 默认 的 横幅 ， 或 者 在 特 
定 activity 的 activity 中 添加 横幅 。 


在 UI 模 式 和 TV 设计 指导 中 查看 Banners。 


添加 TV 支持 库 


Android SDK 包 含 用 于 TV 应 用 的 支持 库 。 这 些 库 为 TV 设备 提供 APl 和 用 户 界 面 控件 。 这 些 库 
位 于 <sdk>/extras/android/support/ 目录 。 以 下 是 这 些 库 的 列表 和 它们 的 作用 介绍 : 


e v17 leanback library - 提供 TV 应 用 的 用 户 界 面 控 件 ， 特 别 是 用 于 媒体 播放 应 用 的 控件 。 
e v7 recyclerview library - 提供 了 内 存 高 效 方式 的 长 列表 的 管理 显示 类 。 有 一 些 v17 
leanback 库 的 类 依赖 于 本 库 的 类 。 


e v7 cardview library - 提供 显示 信息 卡 的 用 户 界面 控件 ， 如 媒体 图 片 和 描述 。 
Note : TV 应 用 中 可 以 不 用 这 些 库 。 ' 我 们 强烈 推荐 使 用 它们 ， 特 别 是 为 应 用 提供 媒 


体 目 录 浏 览 界面 时 。 
如 果 我 们 决定 用 v17 leanback library ， 我 们 应 该 注意 它 依赖 于 v4 support library。 这 意味 着 
要 用 leanback 支 持 库 必须 包含 以 下 所 有 的 支持 库 : 


e v4 support library 
e v7 recyclerview support library 
e v17 leanback support library 


v17 leanback library 包含 资源 文件 ， 需 要 你 在 应 用 中 采取 特定 的 步骤 去 包含 它 。 插 入 带 资 源 
文件 的 支持 库 的 说 明 ， 查 看 Support Library Setup ° 


创建 TV 应 用 


在 完成 上 面 的 步骤 之 后 ， 到 了 给 大 屏幕 创建 应 用 的 时 候 了 ! 检查 一 下 这 些 额 外 的 专题 可 以 帮 
助 我 们 创建 TV 应 用 : 
e 创建 TV 播放 应 用 -TV 就 是 用 来 娱乐 的 ， 因 此 安 草 提供 了 一 套用 户 界 面 工具 和 控件 ， 用 来 
创建 视频 和 音乐 的 TV 应 用 ， 并 且 让 用 户 浏览 想 看 到 的 内 容 。 
e 帮助 用 户 找 到 TV 内 容 - 因为 所 有 的 内 容 选 择 都 用 手指 操作 贷 控 器 ， 所 以 帮助 用 户 找到 想 


要 的 内 容 几 乎 和 提供 内 容 同样 重要 。 这 个 主题 讨论 如 何在 TV 设备 中 处 理 内 容 。 
e TV 游戏 - TV 设备 是 非常 好 的 游戏 平台 。 参 考 这 个 主题 去 创造 更 好 的 TV 游戏 体验 。 


— € , 
运行 TV 应 用 

运行 应 用 是 在 开发 过 程 中 的 一 个 重要 的 部 分 。 在 安 卓 SDK 中 的 AVD 管 理 器 提供 了 创建 虚拟 TV 
设备 的 功能 ， 可 以 让 应 用 在 虚拟 设备 中 运行 和 测试 。 

创建 一 个 虚拟 TV 设备 


1. 打开 AVD 管 理 器 。 更 多 信息 ， 参 考 AVD 管 理 器 帮助 。 

2. 在 AVD 管 理 器 窗口 ， 点 击 Device Definitions 标 签 

3. 选择 一 个 Android TV 设备 描述 ， 并 且 点 击 Create AVD ° 
4. 选择 模拟 器 选项 并 且 点 击 OK 创建 AVD © 


Note : 获得 TV 模拟 器 设 5 最 佳 性 能 ， 打 开 Use Host GPU option ， 支 持 虚 拟 设 备 加 
速 。 更 多 模拟 器 硬件 加 速 信 息 ， 参 考 Using the Emulator 。 


在 虚拟 设备 中 测试 应 用 


1. 在 开发 环境 中 编译 TV 应 用 。 
2， 从 开发 环境 中 运行 应 用 并 选择 目标 为 TV 虚拟 设备 。 


更 多 模拟 器 信息 : Using the Emulator e 用 Android Studio 部 署 应 用 到 模拟 器 ， 查 
Æ Debugging with Android Studio。 用 带 ADT 播 件 的 Eclipse 部 署 应 用 到 模拟 器 ， 查 看 Building 


and Running from Eclipse with ADT 。 


FT ARTVI > 


处 理 TV 硬 件 


编写 :awong1900 - 原文 :http://developer.android.com/training/tv/start/hardware.html 


TV 硬件 和 其 他 Android 设 备 有 实质 性 的 不 同 。TV 不 包含 一 些 其 他 Android 设 备 具 备 的 硬件 特 
性 ， 如 触摸 屏 ， 摄 像 头 ， 和 GPS 。TV 操 作 也 完全 依赖 于 其 他 辅助 硬件 设备 。 为 了 让 用 户 与 TV 
应 用 交互 ， 他 们 必须 使 用 下 控 器 或 者 游戏 手柄 。 当 我 们 创建 TV 应 用 时 ， 必 须 小 心 的 考虑 到 TV 
硬件 的 限制 和 操作 要 求 。 


本 节 课程 讨论 如 何 检查 应 用 是 不 是 运行 在 TV 上 ， 怎 样 去 处 理 不 支持 的 硬件 特性 ， 和 讨论 处 理 
TV 设备 控制 器 的 要 求 。 


TV 设备 的 检测 


如 果 我 们 创建 的 应 用 同时 支持 TV 设备 和 其 他 设备 ， 我 们 可 能 需要 检测 应 用 当前 运行 在 哪 种 设 
备 上 ， 并 调整 应 用 的 执行 。 例 如 ， 如 果 有 一 个 应 用 通过 Intent 启 动 ， 应 用 应 该 检查 设备 特性 然 
后 决定 是 应 该 启动 TV 方面 的 activity 还 是 手机 的 activity。 


检查 应 用 是 


否 运 行 在 TV 设备 上 ， 推 荐 的 方式 是 用 UiModeManager.getCurrentModeType()) 方 
法 检测 设备 是 否 


运行 在 TV 模式 。 下 面 的 示例 代码 展示 了 如 何 检 查 应 用 是 否 运行 在 TV 设备 上 : 


public static final String TAG = "DeviceTypeRuntimeCheck"; 


UiModeManager uiModeManager - (UiModeManager) getSystemService(UI MODE SERVICE); 
if (uiModeManager.getCurrentModeType() -- Configuration.UI MODE TYPE TELEVISION) ( 
Log.d(TAG, "Running on a TV Device") 
relse f 
Log.d(TAG, "Running on a non-TV Device") 


} 


处 理 不 支持 的 硬件 特性 


基于 应 用 的 设计 和 功能 ， 我 们 可 能 需要 在 茶 些 硬件 特性 不 可 用 的 情况 下 工作 。 这 节 讨 论 哪些 
硬件 特性 对 于 TV 是 典型 不 可 用 的 ， 如 何 去 检 测 缺 少 的 硬件 特性 ， 并 且 去 用 这 些 特性 的 推荐 替 
代 方 法 。 


不 支持 的 TV 硬件 特性 


TV 和 其 他 设备 有 不 同 的 目的 ， 因 此 它们 没有 一 些 其 他 Android 设 备 通常 有 的 硬件 特性 。 由 于 这 
个 原因 ，TV 设 备 的 Android 系 统 不 支持 以 下 特性 


硬件 Android 特 性 描述 


触 屏 android.hardware.touchscreen 
触 屏 模 拟 器 android.hardware.faketouch 
电话 android.hardware.telephony 
摄像 头 android.hardware.camera 

TE android.hardware.bluetooth 
近 场 通讯 (NFC) android.hardware.nfc 

GPS android.hardware.location.gps 
A X, [1] android.hardware.microphone 
传感器 android.hardware.sensor 


[1] 一 些 TV 控 制 器 有 麦克 风 ， 但 不 是 这 里 描述 的 麦克 风 硬 件 特 性 。 控 制 器 麦克 风 是 完全 被 


支持 的 。 


查看 Features Reference 获 得 完全 的 特性 和 子 特性 列表 ， 和 它们 的 描述 。 


声明 TV 硬件 需求 


Android 应 用 能 通过 在 manifest 中 定义 硬件 特性 需求 来 确保 应 用 不 能 被 安装 在 不 提供 这 些 特性 
的 设备 上 。 如 果 我 们 正在 扩展 应 用 到 TV 上 ， 和 仔细 地 审查 我 们 的 manifest 的 硬件 特性 需求 ， 它 
有 可 能 阻止 应 用 安装 到 TV 设备 上 。 


即使 我 们 的 应 用 使 用 了 TV 上 不 存在 的 硬件 特性 (如 和 触 屏 或 者 摄像 头 ) ， 应 用 也 可 以 在 没有 那 
些 特性 的 情况 下 工作 ， 需 要 修改 应 用 的 manifest 来 表明 这 些 特性 不 是 必须 的 。 接 下 来 的 
manifest 代 码 片段 示范 了 如 何 声 明 在 TV 设备 中 不 可 用 的 硬件 特性 ， 尽 管 我 们 的 应 用 在 非 TV 设 
备 上 可 能 会 用 上 这 些 特性 。 


«uses-feature android:name="android.hardware. touchscreen" 
android: required="false"></uses> 

<uses-feature android:name-"android.hardware.faketouch" 
android: required="false"></uses> 

<uses-feature android:name="android.hardware.telephony" 
android: required="false"></uses> 

<uses-feature android:name="android.hardware.camera" 
android: required="false"></uses> 

<uses-feature android:name="android.hardware.bluetooth" 
android: required="false"></uses> 

<uses-feature android:name="android.hardware.nfc" 
android: required="false"></uses> 

<uses-feature android: name="android.hardware.gps" 
android: required="false"></uses> 

<uses-feature android:name="android.hardware.microphone" 
android: required="false"></uses> 

<uses-feature android:name="android.hardware.sensor" 
android: required="false"></uses> 


Note : 一 些 特 性 有 子 特性 ， 如 android.hardware.camera.front ° #4 : Feature 
Reference。 确 保 应 用 中 任何 子 特性 也 标记 为 required-"false" ° 


所 有 想 用 在 TV 设备 上 的 应 用 必须 声明 触 屏 特 性 不 被 需要 ， 在 创建 TV 应 用 的 第 一 步 有 描述 。 如 
果 我 们 的 应 用 使 用 了 一 个 或 更 多 的 上 面 列 表 上 的 特性 ， 改 变 manifest 特 性 
的 android:required 属性 为 false 。 


Caution : 表明 一 个 硬件 特性 是 必须 的 ， 设 置 它 的 值 为 true 可 以 阻止 应 用 在 TV 设备 上 安 
装 或 者 出 现在 AndroidTV 的 主屏 幕 局 动 列 表 上 。 


一 旦 我 们 决定 了 应 用 的 硬件 特性 选项 ， 那 就 必须 检查 在 运行 时 这 些 特性 的 可 用 性 ， 然 后 调整 
应 用 的 行为 。 下 一 节 讨 论 如 何 检查 硬件 特性 和 改变 应 用 行为 的 建议 处 理 。 


更 多 关于 filter 和 在 manifest 里 声明 特性 ， 参 考 : uses-feature ° 


声明 权限 会 隐 含 硬件 特性 


—#kuses-permission manifest 声 明 隐 含 了 硬件 特性 。 这 些 行为 意味 着 在 应 用 中 请 求 一 些 权限 
能 导致 应 用 不 能 安装 和 使 用 在 TV 设备 上 。 下 面 普通 的 权限 请 求 包 含 了 一 个 隐 式 的 硬件 特性 需 
T D 


权限 隐 式 的 硬件 需求 
RECORD AUDIO android.hardware.microphone 


android.hardware.camera and 
CAMERA android.hardware.camera.autofocus 


ACCESS COARSE LOCATION android.hardware.location and 


android.hardware.location.network 


ACCESS FINE LOCATION android.hardware.location and 


android.hardware.location.gps 


包含 隐 式 硬件 特性 需求 的 完整 权限 需求 列表 ， 参 考 : Uses-feature。 如 果 我 们 的 应 用 请 求 了 上 
面 列表 上 的 特性 的 任何 一 个 ， 在 manifest 中 设置 它 的 隐 式 硬件 特性 为 不 需要 
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检查 硬件 特性 


Android Tne wer se 性 是 否 可 用 。 用 hasSystemFeature(String)) 
检查 特定 的 特性 。 这 个 方法 只 需要 一 个 字符 囊 参 数 ， 即 想 检查 的 特性 名 字 。 


ove 


fu and 


接 下 来 的 示例 代码 展示 了 如 何在 运行 时 检测 硬件 特性 的 可 用 性 


// Check if the telephony hardware feature is available. 
if (getPackageManager().hasSystemFeature("android.hardware.telephony")) { 
Log.d("HardwareFeatureTest", "Device can make phone calls"); 


} 


// Check if android.hardware.touchscreen feature is available. 
if (getPackageManager().hasSystemFeature("android.hardware.touchscreen")) { 
Log.d("HardwareFeatureTest", "Device has a touch screen."); 


} 


触 屏 


因为 大 部 分 的 TV 没有 触摸 屏 ， 在 TV 设备 上 ，Android 不 支持 触 屏 交 互 。 此 外 ， 用 触 屏 交 互 和 
坐 在 离 显 示 器 3 米 外 观看 是 相互 矛盾 的 。 


在 TV 设备 中 ， 我 们 应 该 设计 出 支持 帝 控 器 方向 键 (D-pad) 远程 操作 的 交互 模式 。 更 多 关于 
正确 地 支持 TV 友好 的 控制 器 操作 的 信息 ， 参 考 Creating TV Navigation 。 


摄像 头 


尽管 TV 通常 没有 摄像 头 ， 但 是 我 们 仍然 可 以 提供 拍照 相关 的 TV 应 用 ， 如 果 应 用 有 拍照 ， 查 看 
和 编辑 图 片 功 能 ， 在 TV 上 可 以 关闭 拍照 功能 但 仍 可 以 允许 用 户 查 看 甚至 编辑 图 片 。 如 果 我 们 
决定 在 TV 上 使 用 摄像 相关 的 应 用 ， 在 manifest 里 添加 接 下 来 的 特性 声明 : 


<uses-feature android:name-"android.hardware.camera" android:required-"false" ></uses> 


如 果 在 缺少 摄像 头 情况 下 运行 应 用 ， 在 我 们 应 用 中 添加 代码 去 检测 是 否 摄像 头 特性 可 用 ， 并 
且 调 整 应 用 的 操作 。 接 下 来 的 示例 代码 展示 了 如 何 检测 一 个 摄像 头 的 存在 : 


// Check if the camera hardware feature is available. 

if (getPackageManager().hasSystemFeature("android.hardware.camera")) { 
Log.d("Camera test", "Camera available!"); 

else { 
Log.d("Camera test", "No camera available. View and edit features only."); 


GPS 


TV 是 国定 的 室内 设备 ， 并 且 没 有 内 置 的 全 球 定位 系统 (GPS) 接收 器 。 如 果 我 们 应 用 使 用 定 
位 信息 ， 我 们 仍 可 以 允许 用 户 搜索 位 置 ， 或 者 用 国定 位 置 提 供 商 代替 ， 如 在 TV 设置 中 设置 邮 
政 编 码 。 


// Request a static location from the location manager 

LocationManager locationManager - (LocationManager) this.getSystemService( 
Context.LOCATION SERVICE); 

Location location = locationManager.getLastKnownLocation("static"); 


// Attempt to get postal or zip code from the static location object 
Geocoder geocoder - new Geocoder(this); 
Address address - null; 


try { 
address - geocoder.getFromLocation(location.getLatitude(), 


location.getLongitude(), 1).get(0); 
Log.d("Zip code", address.getPostalCode()); 


} catch (IOException e) { 
Log.e(TAG, "Geocoder error", e); 


处 理 控制 器 
TV 设备 需要 辅助 硬件 设备 与 应 用 交互 ， 如 一 个 基本 形式 的 氨 控 器 或 者 游戏 手 枉 。 这 意味 着 我 


们 应 用 必须 支持 D-pad (十 字 方 向 键 ) 输入 。 它 也 意味 着 我 们 应 用 可 能 需要 处 理 手柄 掉 线 和 更 
多 类 型 的 手柄 输入 。 


D-pad 最 低 控 制 要 求 


默认 的 TV 设备 控制 器 是 D-pad。 通 常 ， 我 们 可 以 用 遥控 器 的 上 ， 下 ， 左 ， 右 ， 选 择 ， 返 回 ， 
和 Home 键 操作 应 用 。 如 果 应 用 是 一 个 游戏 而 需要 游戏 手柄 额外 的 控制 ， 它 也 应 该 尝试 允许 用 
D-pad 操作 。 这 种 情况 下 ， 应 用 也 应 该 警告 用 户 需 要 手柄 ， 并 且 允 许 他 们 用 D-pad 优雅 的 退出 
游戏 。 更 多 关于 在 TV 设备 如 理 D-pad 的 操作 ， 参 考 Creating TV Navigation。 


处 理 手柄 掉 线 


TV 的 手柄 通常 是 蓝牙 设备 ， 它 为 了 省 电 而 定期 的 休眠 并 且 与 TV 设备 断 开 连接 。 这 意味 着 如 果 
不 处 理 这 些 重 连 事件 ， 应 用 可 能 被 中 断 或 者 重新 开始 。 这 些 事件 可 以 发 生 在 下 面 任何 情景 
v: 


e 当 在 看 几 分 钟 的 视频 ，D-Pad 或 者 游戏 手柄 进入 了 睡眠 模式 ， 从 TV 设备 上 断 开 连接 并 且 
随后 重新 连接 。 
e 在 玩 游戏 时 ， 新 玩家 用 不 是 当前 连接 的 游戏 手柄 加 入 游戏 。 
e 在 玩 游戏 时 ， 一 个 玩家 离开 游戏 并 且 断 开 游戏 手柄 。 
任何 TV 应 用 activity 相 关于 断 开 和 重 连 事件 。 这 些 事件 必须 在 应 用 的 manifest 配 置 去 处 理 。 接 
eee 改变 ， 包 括 键盘 或 者 操作 设备 连接 ， 
断 开 连接 ， 或 者 重新 连 


«activity 
android:name-"com.example.android.TvActivity" 
android: label="@string/app_name" 
android: configChanges="keyboard|keyboardHidden|navigation" 
android: theme="@style/Theme.Leanback"> 


<intent-filter> 
<action android:name="android.intent.action.MAIN" ></action> 
«category android:name-"android.intent.category.LEANBACK LAUNCHER" ></category> 


</intent-filter> 
</activity> 


这 个 配置 改变 属性 允许 应 用 通过 重 连 事 件 继续 运行 ， 比 较 而 言 Android framework 强 制 重启 应 
用 会 导致 一 个 不 好 的 用 户 体 验 。 


处 理 D-pad 变 种 输入 

TV 设备 用 户 可 能 有 超过 一 种 类 型 的 控制 器 来 操作 TV。 例 如 ， 一 个 用 户 可 能 有 基本 D-pad 控制 
器 和 一 个 游戏 控制 器 。 游 戏 控制 器 用 于 D-pad 功能 的 按键 代码 可 能 和 物理 十 字 键 提供 的 不 相 
同 o 


我 们 的 应 用 应 该 处 理 游 戏 控制 器 D-pad 的 变种 输入 ， 这 样 用 户 不 需要 通过 手动 切换 控制 器 去 操 
作 应 用 。 更 多 信息 关于 处 理 这 些 变 种 输入 ， 参 考 Handling Controller Actions 。 


处 理 TV 硬 件 部 分 
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创建 TV 布局 


编写 :awong1900 - Æ x-:http://developer.android.com/training/tv/start/layouts.html 


通常 在 3 米 外 观看 ， 并 且 它 比 大 部 分 Android 设 备 大 的 多 。 这 类 屏 不 能 达到 类 似 小 设备 的 精 
t nn. 这 些 因素 需要 我 们 在 头脑 中 考虑 ， 并 设计 出 对 于 TV 设备 更 为 有 用 且 好 
用 的 应 用 布局 。 


这 节 课 程 描述 了 创建 有 效 的 TV 应 用 布局 的 基本 要 求 和 实现 细 


用 TV 布局 主题 


Android 主 题 能 给 我 们 的 TV 应 用 布局 提供 基础 框架 。 对 于 打算 在 TV 设备 上 运行 的 应 用 
activity， 我 们 应 该 用 一 款 主题 改变 它 的 显示 。 这 节 课 程 教 我 们 应 该 用 哪个 主题 。 


Leanback 主 题 


支持 TV 用 户 界 面 的 库 叫 做 v17 leanback libarary， 它 提供 了 一 个 标准 的 TV activity 主 题 ， 叫 
做 Theme.Leanback 。 这 一 主题 为 TV 应 用 程序 建立 了 一 致 的 视觉 风格 。 强 烈 推 荐 在 任何 用 了 
v17 leanback 类 的 TV 应 用 中 使 用 这 个 主题 。 接 下 来 的 代码 展示 如 何在 应 用 中 对 给 定 的 activity 
使 用 这 个 主题 : 


«activity 
android:name="com.example.android.TvActivity" 
android: label="@string/app_name" 
android: theme="@style/Theme.Leanback"> 


NoTitleBar + €i 


在 手机 和 平板 的 Android 应 用 中 ， 标 题 栏 是 标准 的 用 户 界面 元 素 。 但 是 在 TV 应 用 中 是 不 适合 
的 。 如 果 没 有 用 v17 leanback 类 ， 我 们 应 该 在 TV activity 使 用 这 个 主题 来 隐 去 标题 栏 的 显示 
接 下 来 的 TV 应 用 manifest 代 码 示 范 了 如 何 应 用 这 个 主题 来 删除 标题 栏 。 


o 


«application» 


«activity 
android:name-"com.example.android.TvActivity" 
android:label-"Qstring/app name" 
android: theme="@android:style/Theme.NoTitleBar"> 


</activity> 
</application> 


创建 基本 的 TV 布局 


TV 设备 的 布局 应 该 遵循 一 些 基本 的 指引 确保 它们 在 大 屏幕 下 是 可 用 的 和 有 效率 的 。 遵 循 这 些 
技巧 去 创建 最 优化 的 TV 横 屏 布局 。 


e 创建 横 屏 布局 。TV 屏 幕 总 是 显示 在 横 屏 模式 。 

e 把 导航 控件 放置 在 屏幕 的 左边 或 者 右边 ， 并 且 保 持 内 容 在 重 直 区 间 。 

e 创建 分 离 的 Ul， 用 Fragment， ee eee 
更 好 的 使 用 。 

e 用 框架 如 RelativeLayout 或 者 LinearLayout 来 排列 视图 。 基 于 对 齐 方式 ， 纵 横 比 ， 和 电视 
屏幕 的 像素 密度 ， 这 个 方法 允许 系统 调整 视图 大 小 的 位 置 。 

。 在 布局 控件 之 间 添 加 足够 的 边际 ， 以 避免 成 为 一 个 杂乱 的 Ul。 


Overscan 


由 于 TV 标准 的 演进 ，TV 的 布局 有 一 个 独特 的 需求 是 总 是 希望 给 观众 显示 全 屏 图 像 。 因 为 这 个 
原因 ，TV 设 备 可 能 剪 掉 应 用 布局 的 外 边缘 去 确保 整个 显示 器 被 十 满 。 这 种 行为 通常 简称 为 
overscan » 


避免 屏幕 元 素 由 于 overscan 被 剪 掉 ， 可 以 在 布局 所 有 的 边缘 增加 总 共 10% 的 边际 。 这 换算 为 


在 activity 的 基础 布局 上 左右 边缘 留 48dp 的 边际 和 在 上 下 留 27dp 的 边际 。 接 下 来 的 布局 例子 展 
示 了 如 何在 TV 应 用 根 布局 上 设置 这 些 边 际 。 


<?xml version="1.0" encoding="utf-8"?> 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 


android 
android 
android 
android 
android 
android 
android 
android 


«/LinearLayout» 


:id-"Q-id/base layout" 
:layout width-"match parent" 
:layout height-"match parent" 
:orientation-"vertical" 

: Layout_marginTop="27dp" 

: Layout_marginLeft="48dp" 

: Layout_marginRight="48dp" 

: Layout_marginBottom="27dp" > 


Caution : 如 果 我 们 正在 使 用 v17 leanback 类 ， 不 要 在 布局 中 留 overscan 边 际 ， 诸 如 


BrowseFragment 或 者 相关 控件 ， 因 为 那些 布局 已 经 包含 了 overscan 安 全 边际 


o 


创建 方便 使 用 的 文本 和 控件 


在 TV 应 用 布局 中 的 文本 和 控件 应 该 在 一 定 距 离 外 是 容易 查看 和 导航 的 。 接 下 来 的 技巧 是 确保 
我 们 的 用 户 界 面 元 素 在 一 定 距离 外 更 容易 查看 。 


e 分 解 文本 为 小 块 ， 用 户 可 以 快速 浏览 。 


e “MAR 


下 用 亮色 文字 。 这 种 风格 在 TV 中 更 容易 阅读 。 


e 避免 轻 字 体 或 者 字体 既 罕 且 有 非常 宽阔 的 笔触 效果 。 用 简单 的 sans-serif 字 体 并 且 去 掉 锯 
zu SUR AS Je] iE o 
e 用 Android 标 准 的 字体 大 小 。 


«TextView 


android 
android 
android 
android 


android: 
android: 


:id="@tid/atext" 

: Layout_width="wrap_content" 
:layout height-"wrap content" 
:igravity-"center vertical" 


singleLine-"true" 
textAppearance-"?android:attr/textAppearanceMedium"/» 


i E aas E Du DR dla Ta 
清楚 。 做 这 个 最 好 的 方式 是 用 布局 相对 大 小 而 不 是 绝对 大 小 ， 并 且 用 密度 无 关 像素 
(dip) 单位 代替 像素 单位 。 例 如 ， 设 置 控件 的 宽度 ， 用 wrap content. 代替 特定 像素 值 ， 
并 且 设置 控件 的 边际 ， 用 dip 代 替 px 值 。 更 多 关于 密度 无 关 像 素 和 创建 大 尺寸 屏幕 的 布 
局 ， 查 看 Support Mutiple Screens。 


管理 TV 布局 资源 


通常 的 高 清晰 度 TV 分 辩 率 是 720p，1080i 和 1080p。 假 定 我 们 的 TV 布局 对 象 是 一 个 1920 x 
OB ge A DR ERTAR CD HZ 通常 ， 降 低 分 辨 
3E (删除 像素 ) 不 会 降低 布局 的 外 观 质量 。 但 是 增加 分 辨 率 会 降低 布局 显示 的 质量 ， 并 且 会 
对 用 户 体验 造成 负面 影响 。 


为 了 获得 最 好 的 图 像 缩放 效果 ， 尽 可 能 提供 9-patch 图 片 元 素 。 如 果 在 我 们 的 布局 中 使 用 低 质 
量 或 者 小 的 图 片 ， 它 们 将 出 现 马赛 克 ， 模 糊 或 者 颗粒 ， 这 不 是 一 个 好 的 用 户 体验 。 用 高 质量 
图 片 代 替 它 。 


更 多 关于 优化 布局 和 大 屏幕 的 资源 文件 问题 ， 参 考 Designing for multiple screens ° 
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避免 反 模 式 布局 

有 几 种 创建 布局 的 方法 我 们 应 该 避免 使 用 ， 因 为 它们 不 能 在 TV 设备 上 很 好 的 工作 并 且 导 致 不 
好 的 用 户 体 验 。 当 开发 TV 布局 时 ， 以 下 一 些 用 户 界面 是 我 们 应 该 明确 不 能 使 用 的 。 


e 重用 手机 和 平板 布局 - 不 要 重用 没有 修改 的 手机 或 者 平板 应 用 的 布局 。 为 其 他 Android 设 
备 开发 的 布局 不 适合 TV 设备 ， 并 且 TV 上 布局 应 该 被 简化 。 


e 状态 栏 - 尽管 这 种 用 户 界 面 习 惯 是 推荐 使 用 在 手机 和 平板 上 ， 但 是 他 不 适合 TV 界面 。 通 
常 ， 状 态 栏 选项 菜单 〈 或 者 任何 下 拉 菜 单 ) 坚决 不 要 使 用 ， 因 为 用 和 控 器 操作 这 样 的 菜 


单 是 困难 的 。 
。 ViewPager - 在 屏幕 之 间 滑 动能 很 好 在 手机 或 平板 上 工作 ， 但 是 不 要 在 TV 上 尝试 ! 更 多 
言 息 关 于 设计 适合 TV 的 布局 ， 参 考 TV Design 指 导 。 


处 理 大 图 片 


TV 设备 ， 像 任何 其 他 Android 设 备 ， 内 存 有 一 定 限 制 。 如 果 我 们 创建 的 应 用 中 用 了 很 高 分 辨 率 
的 图 片 或 者 用 了 很 多 高 分 辨认 图 片 ， 它 可 能 很 快 达到 内 存 限制 ， 并 且 导 致 内 存 溢出 错误 。 避 
免 这 些 类 型 的 问题 ， 遵 循 以 下 方法 : 


e 仅 当 图 片 显示 在 屏幕 时 才 加 载 。 例 如 ， 当 在 GridView 或 者 Gallery 中 显示 多 个 图 片 时 ， 仅 
当 getView()) 在 视图 的 Adapter 中 被 调用 时 才 加 载 图 片 。 

e 在 Bitmap 视 图 中 调用 recycle()) 不 再 需要 。 

e 对 存储 在 内 存 中 集合 中 的 位 图 对 象 使 用 弱 引 用 。 

© 如 果 我 们 从 网 络 上 获取 图 片 ， 用 AsyncTask 去 操作 并 且 存 储 它 们 在 设备 上 以 方便 更 快 的 存 
取 。 绝 对 不 要 在 应 用 的 主线 程 操 作 网 络 传输 。 

e 当下 载 大 图 片 时 ， 降 低 图 片 到 合适 的 尺寸 ， 否 则 ， 下 载 图 片 本 身 可 能 导致 内 存 溢出 问 
题 。 更 多 信息 关于 获得 最 好 的 图 片 操 作 性 能 ， 参 考 Displaying Bitmaps Efficiently 。 


共有 效 的 广告 


Android TV 的 广告 必须 总 是 全 屏 。 广 告 不 可 以 出 现在 内 容 的 这 边 或 者 窗 盖 内 容 。 用 户 应 当 能 
用 D-pad 控制 器 关闭 广告 。 视 频 广 告 在 开始 时 间 后 的 30 秒 内 应 当 能 被 关闭 。 


Android TV 不 提供 网 页 浏览 器 。 我 们 的 广告 不 应 该 尝试 去 启动 网 页 浏览 器 或 者 重 定向 到 
Google Play 商 店 。 


Note : WebView 类 用 于 登入 服务 器 ， 如 Google+ 和 Facebook 。 
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创建 TV 导航 


编写 :awong1900 - Æ x-:http://developer.android.com/training/tv/start/navigation.html 


TV 设备 为 应 用 程序 提供 一 组 有 限 的 导航 控件 。 为 我 们 的 TV 应 用 创建 有 效 的 导航 方案 取决 于 理 
解 这 些 有 限 的 控件 和 用 户 操作 应 用 时 的 限制 。 因 此 当 我 们 为 TV 创建 Android 应 用 时 ， 额 外 注意 
用 户 是 用 中 控 器 按键 ,而 不 是 用 触摸 屏 导 航 我 们 的 应 用 程序 。 


这 节 课 解释 了 创建 有 效 的 TV 应 用 导航 方案 的 最 低 要 求 和 如 何 对 应 用 程序 使 用 这 些 要 求 。 


使 用 D-pad 导航 


在 TV 设备 上 ， 用 户 用 下 控 器 设备 的 方向 手柄 (D-pad) 或 者 方向 键 去 控制 控件 。 这 类 控制 器 
限制 为 上 下 左右 移动 。 为 了 创建 最 优化 的 TV 应 用 ， 我 们 必须 提供 一 个 用 户 能 快速 学 习 如 何 使 
用 有 限 控件 导航 的 方案 。 


Android framework 自 动 地 处 理 布局 元 素 之 间 的 方向 导航 操作 ， 因 此 我 们 不 需要 在 应 用 中 做 额 
外 的 事情 。 不 管 怎 样 ， 我 们 也 应 该 用 D-pad 控制 器 实际 测试 去 发 现任 何 导 航 问题 。 接 下 来 的 指 
引 是 如 何在 TV 设备 上 用 D-pad 测试 应 用 的 导航 。 
e 确保 用 户 能 用 D-pad 控制 器 导航 所 有 屏幕 可 见 的 控件 。 
e 对 于 滚动 列表 上 的 焦点 ， 确 保 D-pad 上 下 键 能 滚动 列表 ， 并 且 确 定 键 能 选择 列表 中 的 项 。 
检查 用 户 可 以 选择 列表 中 的 元 素 并 且 选 中 元 素 后 仍 可 以 滚动 列表 。 
e 确保 在 控件 之 间 切 换 是 直接 的 和 可 预测 的 。 


修改 导航 的 方向 


基于 布局 元 素 中 可 选中 的 元 素 的 相对 位 置 ，Android framwork 自 动 应 用 导航 方向 方案 。 我 们 应 
该 用 D-pad 控制 器 测试 生成 的 导航 方案 。 在 测试 后 ， 如 果 我 们 想 规定 用 户 以 一 个 特定 的 方式 在 
布局 中 移动 ， 我 们 可 以 在 控件 中 设置 明确 的 导航 方向 。 


Note: 如 果 系 统 使 用 的 默认 顺序 不 是 很 好 ， 我 们 应 该 仅 用 这 些 属性 去 修改 导航 顺序 。 


接 下 来 的 示例 代码 展示 如 何 为 TextView 布 局 控件 定义 下 一 个 控件 焦点 。 


«TextView android:id="@+id/Category1" 
android:nextFocusDown="@+id/Category2"\> 


接 下 来 的 列表 展示 了 用 户 接 口 控件 所 有 可 用 的 导航 属性 。 


属性 功能 


nextFocusDown 定义 用 户 按 下 导航 时 的 焦点 
nextFocusLeft 定义 用 户 按 左 导航 时 的 焦点 
nextFocusRight 定义 用 户 按 右 导航 时 的 焦点 
nextFocusUp 定义 用 户 按 上 导航 时 的 焦点 


去 使 用 这 些 明确 的 导航 属性 ， 设 置 另 一 个 布局 控件 的 ID 值 ( android:id 值 ) 。 我 们 应 该 设置 
导航 顺序 为 一 个 循环 ， 因 此 最 后 一 个 控件 返回 至 第 一 个 焦点 。 


提供 清楚 的 焦点 和 选中 状态 


在 TV 设备 上 的 应 用 ou 决定 屏幕 上 界面 元 素 的 焦点 。 如 果 
我 们 不 提供 清晰 的 焦点 项 显示 (和 用 户 能 操作 的 选项 ) ， 他 们 会 很 快 泄气 并 退出 我 们 的 应 

用 。 同 样 的 原因 ， 重 要 的 是 当 我 们 的 应 用 开始 或 者 任何 无 操作 的 时 间 中 ， 总 是 有 焦点 项 可 以 
立即 操作 。 


我 们 的 应 用 布局 和 实现 应 该 用 颜色 ， 大 小 ， 动 画 或 者 它们 组 在 一 起 来 帮助 用 户 容 易 地 决定 下 
一 步 操作 。 在 应 用 中 用 一 致 的 焦点 显示 方案 。 


Android 提 供 Drawable State List Resources 来 实现 高 亮 选中 的 焦点 。 接 下 来 的 示例 代码 展示 
了 如 何 为 用 户 导 航 到 控件 并 选择 它 时 使 用 视觉 化 按钮 显示 : 


<!-- res/drawable/button.xml --> 

<?xml version="1.0" encoding="utf-8"?> 

«selector xmlns:android="http://schemas.android.com/apk/res/android"> 
<item android:state_pressed="true" 


android: drawable="@drawable/button_pressed" /> <!-- pressed --> 
<item android:state_focused="true" 
android: drawable="@drawable/button_focused" /> <!-- focused --> 
<item android:state_hovered="true" 
android: drawable="@drawable/button_focused" /> <!-- hovered --> 
<item android: drawable="@drawable/button_normal" /> «!-- default --> 
</selector> 


接 下 来 的 XML 示例 代码 对 按钮 控件 应 用 了 上 面 的 按键 状态 列表 drawable : 


<Button 
android:layout height-"wrap content" 
android:layout width-"wrap content" 
android: background="@drawable/button" /> 


确保 在 可 定 为 焦点 的 和 可 选中 的 控件 中 提供 了 充分 的 填充 ， 以 便 围 绕 它 们 的 高 亮 是 清楚 的 。 


创建 TV 的 导航 栏 


更 多 建议 关于 TV 应 用 中 设计 有 效 的 选中 和 焦点 ， 看 Patterns of TV。 


下 一 节 : 创建 TV 播放 应 用 > 
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创建 TV 播放 应 用 


编写 :huanglizhuo - 原文 :http://developer.android.com/training/tv/playback/index.html 


浏览 和 播放 媒体 文件 往往 是 由 一 个 TV 应 用 程序 提供 的 用 户 体 验 的 一 部 分 。 从 头 开始 构建 这 样 
的 体验 ， 并 同时 确保 它 是 快速 ， 流 电 ， 和 有 吸引 力 的 是 具有 相当 挑战 性 的 。 您 的 应 用 程序 提 
供 访问 媒体 类 别 无 论 大 小 ， 允 许 用 户 快速 浏览 选项 ， 并 获得 他 们 想 要 的 内 容 是 很 重要 的 。 


Android 框 架 通 过 v17 leanback support library 为 构建 用 户 界面 提供 接口 。 该 库 提供 类 来 创建 
用 于 浏览 和 播放 多 媒体 的 高 效 框架 ,为 开发 者 减少 代码 。 该 类 可 以 进行 扩展 和 定制 ， 所 以 我 们 
可 以 为 我 们 的 应 用 程序 创建 一 个 独特 的 高 效 的 类 。 


这 节 课 将 向 您 介绍 如 何 用 Leanback 的 支持 库 构 建 用 于 浏览 和 播放 TV 媒体 内 容 的 TV 应 用 程序 。 


e 创建 一 个 类 别 浏览 器 
学 习 如 何 使 用 Leanback 的 支持 库 ， 建 立 一 个 媒体 类 别 的 浏览 界面 。 
e 提供 一 个 卡片 View 
学 习 使 用 Leanback 的 支持 库 ， 建 立 一 个 卡片 视图 的 内 容 项 目 。 
e. 创建 详细 信息 View 
学 习 使 用 Leanback 的 支持 库 ， 建 立 一 个 详细 内 容 展 示 页 。 
e 显示 正在 播放 卡片 


学 习 如 何 使 用 MediaSession 在 主屏 幕 上 显示 正在 播放 。 


创建 目录 浏览 器 


编写 :huanglizhuo - 原文 :http://developer.android.com/training/tv/playback/browse.html 


Wl 


在 TV 上 运行 的 多 媒体 应 用 得 允许 用 户 浏览 ,选择 和 播放 它 所 提供 的 内 容 。 目 录 浏 览 器 的 用 户 体 
验 要 简单 和 直观 ， 以 及 赏心悦目 ， 引 人 入 胜 。 

这 节 课 讨论 如 何 使 用 的 V17 Leanback 库 提供 的 类 来 实现 用 户 界 面 ， 用 于 从 您 的 应 用 程序 的 媒 
体 目 录 浏 览 音乐 或 视频 。 


创建 一 个 目录 布局 


leanback 类 库 中 的 BrowseFragment 允 许 您 用 最 少 的 代码 创建 一 个 用 于 按 行 浏览 的 主 布局 ,下 
面 的 例子 将 演示 如 何 创建 包含 BrowseFragment 的 布局 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android: layout_width="match_parent" 
android: layout_height="match_parent" 
android: orientation="vertical" 


> 
<fragment 
android: name="android.support.v17.leanback.app.BrowseFragment" 
android: id="@+id/browse_fragment" 
android: layout_width="match_parent" 
android:layout height-"match parent" 
UE 
</LinearLayout> 


A 1 4& activity 工作 ,需要 在 布局 中 取 回 BrowseFragment 的 元 素 。 使 用 这 个 类 中 的 方法 设置 显 
示 参 数 ,如 图 标 ,标题 ,以 及 该 类 别 是 否 可 用 。 下 面 的 代码 简单 的 演示 了 怎样 设 
置 BrowseFragment 布 局 参数 : 


public class BrowseMediaActivity extends Activity { 
public static final String TAG ="BrowseActivity"; 
protected BrowseFragment mBrowseFragment; 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.browse fragment); 


final FragmentManager fragmentManager - getFragmentManager(); 
mBrowseFragment = (BrowseFragment) fragmentManager.findFragmentById( 


R.id.browse fragment); 


// Set display parameters for the BrowseFragment 
mBrowseFragment.setHeadersState(BrowseFragment.HEADERS ENABLED); 
mBrowseFragment.setTitle(getString(R.string.app name)); 
mBrowseFragment.setBadgeDrawable(getResources().getDrawable( 
R.drawable.ic launcher)); 
mBrowseFragment.setBrowseParams(params); 


显示 媒体 列表 


BrowseFragment 允 许 您 定义 和 使 用 adapter 和 presenter 定义 显示 可 浏览 媒体 内 容 类 别 和 媒 
体 项 目 。Adapters 允许 我 们 连接 本 地 或 网 络 数据 资源 。Presenters 操 控 的 媒体 项 目的 数据 ， 
并 提供 布局 信息 在 屏幕 上 显示 的 项 目 。 


下 面 的 示例 代码 演示 了 一 个 为 显示 字符 串 数 据 的 Presenters 的 实现 


public class StringPresenter extends Presenter { 
private static final String TAG - "StringPresenter"; 


public ViewHolder onCreateViewHolder(ViewGroup parent) { 
TextView textView - new TextView(parent.getContext()); 
textView.setFocusable(true); 
textView.setFocusableInTouchMode(true); 
textView.setBackground( 
parent.getContext().getResources().getDrawable(R.drawable.text bg)); 
return new ViewHolder(textView); 


public void onBindViewHolder(ViewHolder viewHolder, Object item) { 
((TextView) viewHolder.view).setText(item.toString()); 


public void onUnbindViewHolder(ViewHolder viewHolder) ( 
// no op 


当 我 们 已 经 为 我 们 的 媒体 项 目 构建 了 一 个 Presenter 类 ， 我 们 可 以 为 BrowseFragment 建 立 并 
添加 一 个 适配器 并 在 屏幕 上 显示 这 些 媒体 项 目 。 下 面 的 示例 代码 演示 了 如 何 用 
StringPresenter 类 构造 一 个 类 别 和 项 目 适 配器 : 


private ArrayObjectAdapter mRowsAdapter; 
private static final int NUM ROWS - 4; 


@Override 
protected void onCreate(Bundle savedInstanceState) { 


buildRowsAdapter(); 


private void buildRowsAdapter() 1 
mRowsAdapter - new ArrayObjectAdapter(new ListRowPresenter()); 


for (int i = 0; i « NUM ROWS; ++i) { 
ArrayObjectAdapter listRowAdapter - new ArrayObjectAdapter( 
new StringPresenter()); 
listRowAdapter.add("Media Item 1"); 
listRowAdapter.add("Media Item 2"); 
listRowAdapter.add("Media Item 3"); 
HeaderItem header = new HeaderItem(i, "Category " + i, null); 
mRowsAdapter.add(new ListRow(header, listRowAdapter)); 


mBrowseFragment.setAdapter(mRowsAdapter); 


这 个 例子 显示 了 静态 实现 适配器 。 典 型 的 媒体 浏览 器 使 用 网 络 数据 库 或 网 络 服务 。 使 用 从 网 
络 取 回 的 数据 做 的 媒体 浏览 器 ,参看 例子 Android TV 


Sj 


更 新 背景 


为 了 给 媒体 浏览 应 用 增加 视觉 趣味 ， 我 们 可 以 在 用 户 浏览 的 内 容 时 更 新 背景 图 片 。 这 种 技术 
可 以 让 我 们 的 应 用 程序 的 互动 感 倍增 。 


Leanback 库 提供 了 BackgroundManager 类 为 我 们 的 TV 应 用 的 activity 更 换 背 景 。 下 面 的 例子 
演示 了 如 何 创 建 一 个 简单 的 方法 更 换 背 景 : 


protected void updateBackground(Drawable drawable) { 
BackgroundManager .getInstance(this) .setDrawable(drawable) ; 


多 现 有 的 媒体 浏览 应 用 在 用 户 浏览 媒体 列表 自动 更 新 的 背景 。 为 了 做 到 这 一 点 ， 我 们 可 以 
sos ， 根据 用 户 的 当前 选择 自动 更 新 背景 。 下 面 的 例子 演示 了 如 何 建立 一 
个 OnltemViewSelectedListener 监 听 选 择 事件 并 更 新 背景 : 


protected void clearBackground() { 
BackgroundManager.getInstance(this).setDrawable(mDefaultBackground); 


protected OnItemViewSelectedListener getDefaultItemViewSelectedListener() { 
return new OnItemViewSelectedListener() { 


@Override 
public void onItemSelected(Object item, Row row) { 


if (item instanceof Movie ) { 
URI uri = ((Movie)item).getBackdropURI(); 


updateBackground(uri); 


) else { 
clearBackground(); 


un 


注意 :以 上 的 示例 是 为 了 简单 。 当 我 们 在 自己 的 应 用 程序 创建 这 个 功能 ， 我 们 应 该 考虑 运 
行 在 一 个 单独 的 线程 在 后 人 台 更 新 操作 获得 更 好 的 性 能 。 此 外 ， 如 果 我 们 正 计 划 在 用 户 触 
发 项 目 ii 更 新 背景 ， 考 虑 增加 一 个 时 延 ， 直 到 用 户 停止 操作 时 再 更 新 背景 图 像 。 这 


样 可 以 避免 过 多 的 背景 图 片 的 更 新 。 


下 一 节 : 提供 一 个 卡片 View > 


提供 一 个 Card 视 图 


编写 : - 原文 : 
在 前 面 的 课程 中 ， 我 们 创建 一 个 目录 浏览 器 ， 实 现 了 浏览 fragment， 显 示 了 媒体 项 目的 列 
表 。 在 本 课程 中 ， 我 们 将 创建 该 卡 视图 的 媒体 项 目 ， 并 在 浏览 fagment 中 呈现 出 来 。 
类 以 及 子 类 显示 与 媒体 项 目 相 关联 的 元 数据 。 在 本 节 课 程 中 使 用 的 
类 显示 随 着 媒体 项 目的 标题 内 容 的 图 像 。 
这 节 课 介绍 了 GitHub 上 的 示例 应 用 程序 代码 。 使 用 该 示例 代 
码 ， 开 始 我 们 自己 的 应 用 程序 。 











创建 一 个 卡片 呈现 者 


生成 视图 并 把 类 和 它们 绑 定 起 来 。 在 我 们 的 浏览 fragment 中 将 内 容 呈 现 给 用 户 ,我 
们 为 内 容 卡 片 创建 并 把 它 传 给 适配器 然后 将 内 容 呈 现在 屏幕 上 。 在 下 面 的 代码 
中 ,CardPresenter 在 的 ) 方 法 中 被 创建 。 


@Override 
public void onLoadFinished(Loader<HashMap<String, List<Movie>>> arg0, 
HashMap<String, List<Movie>> data) { 


mRowsAdapter = new ArrayObjectAdapter(new ListRowPresenter()); 
CardPresenter cardPresenter = new CardPresenter(); 


int i = 0; 


for (Map.Entry<String, List<Movie>> entry : data.entrySet()) { 
ArrayObjectAdapter listRowAdapter = new ArrayObjectAdapter(cardPresenter); 
List<Movie> list = entry.getValue(); 


for (int j = 0; j < list.size(); j++) { 
listRowAdapter.add(list.get(j)); 
} 


HeaderItem header = new HeaderItem(i, entry.getKey(), null); 
itt; 


f 


mRowsAdapter.add(new ListRow(header, listRowAdapter)); 


HeaderItem gridHeader = new HeaderItem(i, getString(R.string.more samples), 
null); 


GridItemPresenter gridPresenter - new GridItemPresenter(); 
ArrayObjectAdapter gridRowAdapter - new ArrayObjectAdapter(gridPresenter); 
gridRowAdapter.add(getString(R.string.grid view)); 
gridRowAdapter.add(getString(R.string.error fragment)); 
gridRowAdapter.add(getString(R.string.personal settings)); 
mRowsAdapter.add(new ListRow(gridHeader, gridRowAdapter)); 


setAdapter (mRowsAdapter); 


updateRecommendations(); 


创建 一 个 卡片 视图 


在 这 步 中 ,我 们 将 用 view holder 创 建 一 个 卡片 presenter 来 为 卡片 视图 呈现 媒体 项 目 。 注 意 ,每 个 
presenter 只 能 创建 一 个 view 类 别 。 如 果 我 们 有 俩 个 不 同 的 卡片 视图 ,我 们 就 得 创建 俩 个 不 同 的 
presenter 


在 presenter 实 现 onCreateViewHolder) 时 创建 一 个 可 以 呈现 内 容 项 目的 view holder ° 


@Override 
public class CardPresenter extends Presenter { 


private Context mContext; 

private static int CARD_WIDTH = 313; 
private static int CARD_HEIGHT = 176; 
private Drawable mDefaultCardImage; 


@Override 
public ViewHolder onCreateViewHolder(ViewGroup parent) { 
mContext = parent.getContext(); 
mDefaultCardImage = mContext.getResources().getDrawable(R.drawable.movie); 


在 onCreateViewHolden) 方 法 中 ,创建 呈现 内 容 的 卡片 视图 。 下 面 的 例子 用 的 是 ImageCardView 


当 卡 片 被 选中 时 ,默认 的 行为 是 放大 展开 。 如 果 我 们 想 创建 不 同 闫 色 的 卡片 可 以 向 下 面 这 样 调 
用 setSelected) 方 法 中 实现 。 


ImageCardView cardView = new ImageCardView(mContext) { 
@Override 
public void setSelected(boolean selected) { 
int selected_background = mContext.getResources().getColor(R.color.detail_ 
background); 
int default_background = mContext.getResources().getColor(R.color.default_ 
background); 
int color = selected ? selected background : default background; 
findViewById(R.id.info field).setBackgroundColor(color); 
super.setSelected(selected); 


}; 


当 用 户 打 开 我 们 的 应 用 时 ,PresenterViewHolder 为 内 容 项 目 显示 了 卡片 视图 。 我 们 需要 调 
用 setFocusable(true) ) 和 setFocusablelnTouchMode(true)) 方 法 设置 接收 来 自 D-pad 的 焦点 控 
制 。 


cardView.setFocusable(true); 
cardView. setFocusableInTouchMode( true) ; 
return new ViewHolder(cardView); 


当 用 户 选中 ImageCardView 时 , 它 用 我 们 制定 的 颜色 背景 展开 文字 内 容 ,就 像 下 面 这 样 。 
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Explore Treasure.. Introducing Google. Introducing Google. YouTube's ready to. 


Introducing Gmail Blue 





下 一 节 : 创建 详细 信息 View > 


创建 详情 


编写 :huanglizhuo - /& x-:http://developer.android.com/training/tv/playback/details.html 


交 | 


待 认领 进行 编写 ， 有 意向 的 小 伙伴 ， 可 以 直接 修改 对 应 的 markdown 文 件 ， 进 行 提 交 


v17 leanback support library 库 提供 的 媒体 浏览 接口 包含 显示 附加 媒体 信息 的 类 ,比如 描述 和 
预览 ,以 及 对 项 目的 操作 ,比如 购买 或 播放 。 


这 节 课 讨论 如 何 为 媒体 项 目的 详细 信息 创建 presenter 类 ， 以 及 用 户 选择 一 个 媒体 项 目 时 如 何 
扩展 DetailsFragment 类 来 实现 显示 媒体 详细 信息 视图 。 


小 贴 士 : 这 里 的 实现 例子 用 的 是 包含 DetailsFragment 的 附加 activity。 但 也 可 以 在 同一 
activity 中 用 fragment 转换 将 BrowseFragment 替 换 为 DetailsFragment. 更 多 关于 
fragment 的 信息 请 参考 Building a Dynamic UI with Fragments 


创建 详细 Presenter 


在 leanback 库 提供 的 媒体 浏览 框架 中 ,可 以 用 presenter 对 象 控制 屏幕 显示 数据 ,包括 媒体 详细 信 
息 。AbstractDetailsDescriptionPresenter 类 提供 的 框架 几乎 是 媒体 项 目 详细 信息 的 完全 继 
承 。 我 们 只 需要 实现 onBindDescription() 方 法 , 像 下 面 这 样 把 数据 信息 和 视图 绑 定 起 来 。 


public class DetailsDescriptionPresenter 
extends AbstractDetailsDescriptionPresenter { 


@Override 
protected void onBindDescription(ViewHolder viewHolder, Object itemData) { 


MyMediaItemDetails details = (MyMediaItemDetails) itemData; 

// In a production app, the itemData object contains the information 
// needed to display details for the media item: 

// viewHolder.getTitle().setText(details.getShortTitle()); 


// Here we provide static data for testing purposes: 
viewHolder.getTitle().setText(itemData.toString()); 
viewHolder.getSubtitle().setText("2014 Drama TV-14"); 
viewHolder.getBody().setText("Lorem ipsum dolor sit amet, consectetur 
* "adipisicing elit, sed do eiusmod tempor incididunt ut labore " 
* " et dolore magna aliqua. Ut enim ad minim veniam, quis " 
+ "nostrud exercitation ullamco laboris nisi ut aliquip ex ea " 
十 


"commodo consequat."); 


扩展 详细 fragment 
当 使 用 DetailsFragment 类 显示 我 们 的 媒体 项 目 详细 信息 时 ,扩展 该 类 并 提供 像 预览 图 片 ,操作 
等 附加 内 容 。 我 们 也 可 以 提供 一 系列 的 相关 媒体 信息 。 


下 面 的 例子 演示 了 怎样 用 presenter 类 为 媒体 项 目 添 加 预览 图 片 和 操作 。 这 个 例子 也 演示 了 添 
加 相关 媒体 行 。 


public class MedialtemDetailsFragment extends DetailsFragment { 
private static final String TAG = "MediaItemDetailsFragment"; 
private ArrayObjectAdapter mRowsAdapter; 


@Override 

public void onCreate(Bundle savedInstanceState) { 
Log.i(TAG, "onCreate"); 
super .onCreate(savedInstanceState) ; 


buildDetails(); 


private void buildDetails() { 
ClassPresenterSelector selector = new ClassPresenterSelector(); 
// Attach your media item details presenter to the row presenter: 
DetailsOverviewRowPresenter rowPresenter = 
new DetailsOverviewRowPresenter(new DetailsDescriptionPresenter()); 


selector.addClassPresenter(DetailsOverviewRow.class, rowPresenter); 
selector.addClassPresenter(ListRow.class, 

new ListRowPresenter()); 
mRowsAdapter - new ArrayObjectAdapter(selector); 


Resources res - getActivity().getResources(); 
DetailsOverviewRow detailsOverview - new DetailsOverviewRow( 
"Media Item Details"); 


// Add images and action buttons to the details view 
detailsOverview.setImageDrawable(res.getDrawable(R.drawable.jelly beans)); 
detailsOverview.addAction(new Action(1, "Buy $9.99")); 
detailsOverview.addAction(new Action(2, "Rent $2.99")); 


mRowsAdapter.add(detailsOverview); 


// Add a Related items row 

ArrayObjectAdapter listRowAdapter - new ArrayObjectAdapter( 
new StringPresenter()); 

listRowAdapter.add("Media Item 1"); 

listRowAdapter.add("Media Item 2"); 

listRowAdapter.add("Media Item 3"); 

HeaderItem header = new HeaderItem(0, "Related Items", null); 

mRowsAdapter.add(new ListRow(header, listRowAdapter)); 


setAdapter(mRowsAdapter); 


创建 详细 信息 activity 


% DetailsFragmenti& 4£ 8 fragment 为 了 使 用 必须 包含 activity。 为 我 们 的 详细 信息 与 


浏览 分 开创 建 activity 并 通过 传递 Intent 打 开 。 这 节 演 示 9 | 建 一 个 包含 媒体 详细 信息 的 
activity。 


创建 详细 信息 前 先 为 DetailsFragment 创 建 一 个 布局 文件 : 


«!-- file: res/layout/details.xml --> 


«fragment xmlns:android-"http://schemas.android.com/apk/res/android" 
android:name="com.example.android.mediabrowser .MedialtemDetailsFragment" 
android: id="@+id/details_fragment" 
android: layout_width="match_parent" 
android:layout height-"match parent" 

/? 


接 下 来 用 上 面 的 布局 文件 创建 一 个 activity: 


public class DetailsActivity extends Activity 


t 
@Override 
public void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
setContentView(R.layout.details); 
} 
} 


V 


后 在 manifest 文 件 中 申明 activity。 记 得 添加 Leanback 主 题 以 确保 用 户 界面 中 有 媒体 浏览 
activity。 


«application» 
«activity android:name=".DetailsActivity" 
android:exported-"true" 


android: theme="@style/Theme.Leanback"/> 


</application> 


为 点击 项 目 添 加 Listener 


实现 DetailsFragment 后 ,在 用 户 点 击 媒体 条 目 时 将 我 们 的 媒体 浏览 View 切 换 详细 信息 view » A 
了 确保 动作 的 实现 ,在 BrowserFragment 中 添加 [OnltemViewClickedListenen] 通 过 Intent 开 局 详 
细 信 息 activity。 


下 面 的 例子 演示 了 实现 怎样 在 媒体 浏览 view 中 实现 一 个 listener 开 启 详细 信息 view © 


public class BrowseMediaActivity extends Activity { 


@Override 
protected void onCreate(Bundle savedInstanceState) { 


// create the media item rows 
buildRowsAdapter(); 


// add a listener for selected items 
mBrowseFragment.OnItemViewClickedListener( 
new OnItemViewClickedListener() { 
@Override 
public void onItemClicked(Object item, Row row) { 
System.out.println("Media Item clicked: " + item.toString()); 
Intent intent = new Intent(BrowseMediaActivity.this, 
DetailsActivity.class); 
// pass the item information 
intent.getExtras().putLong("id", item.getId()); 
startActivity(intent); 


J); 


节 : 显示 正在 播放 卡片 > 


显示 正在 播放 卡片 


编写 :huanglizhuo - 原文 :http://developer.android.com/training/tv/playback/now- 
playing.html 
TV 应 用 允许 用 户 在 使 用 其 他 应 用 时 后 台 播 放 音 乐 或 其 他 媒体 。 如 果 我 们 的 应 用 程序 允许 后 
台 ， 它 必须 要 为 用 户 提供 返回 该 应 用 暂停 音乐 或 切换 到 一 个 新 的 歌曲 的 方法 。Android 框 架 允 
许 TV 应 用 通过 在 主屏 幕 上 显示 正在 播放 卡 做 到 这 一 点 。 
正在 播放 卡片 是 系统 的 组 建 , 它 可 et E 包括 了 媒体 元 数 


据 ， 如 专辑 封面 ， 标 题 和 应 用 程序 图 标 。 当 用 户 选 > 系统 将 打开 拥有 该 会 话 的 应 用 程 
序 。 


这 节 课 将 演示 如 何 使 用 MediaSession 类 实现 正在 播放 卡片 。 


2 媒体 会 话 


一 个 播放 应 用 可 以 作为 activity 或 者 service 运行 。service 是 当 activity 结束 时 依然 可 以 后 台 
播放 的 。 在 这 节 讨 论 中 ,媒体 播放 应 用 是 假设 在 MediaBrowserService 下 运行 的 。 


在 service 的 onCreate()) 方 法 中 创建 一 个 新 的 MediaSession ), 设 置 适当 的 回调 函数 和 标志 ,并 
设置 MediaBrowserService 令 牌 。 


mSession = new MediaSession(this, "MusicService"); 

mSession.setCallback(new MediaSessionCallback()); 

mSession.setFlags(MediaSession.FLAG HANDLES MEDIA BUTTONS | 
MediaSession.FLAG HANDLES TRANSPORT CONTROLS); 


// for the MediaBrowserService 
setSessionToken(mSession.getSessionToken()); 


注意 :正在 播放 卡片 只 有 在 媒体 会 话 设置 了 
FLAG HANDLES _TRANSPORT_CONTROLS 标 志 时 在 可 以 显示 。 


显示 正在 播放 卡片 


如 果 会 话 是 系统 最 高 优先 级 的 会 话 那 么 正在 播放 卡片 将 在 setActivity(true)) 调 用 后 。 同 时 
我 们 的 应 用 必须 像 在 Managing Audio Focus 一 节 中 那样 请 求 音频 焦点 。 


private void handlePlayRequest() { 


tryToGetAudioFocus(); 


if (!mSession.isActive()) { 
mSession.setActive(true); 


如 果 另 一 个 应 用 发 起 媒体 播放 请 求 并 调用 setActivity(false)) 后 这 个 卡片 将 从 主屏 上 移 除 。 


更 新 播放 状态 


正如 任何 媒体 的 应 用 程序 ， 在 MediaSession 中 更 新 播放 状态 ， 使 卡片 可 以 显示 当前 的 元 数 
据 ， 如 在 下 面 的 例子 : 


private void updatePlaybackState() { 


} 


long position = PlaybackState.PLAYBACK POSITION UNKNOWN; 
if (mMediaPlayer !- null && mMediaPlayer.isPlaying()) { 

position - mMediaPlayer.getCurrentPosition(); 
à 
PlaybackState.Builder stateBuilder = new PlaybackState.Builder() 

.setActions(getAvailableActions()); 

stateBuilder.setState(mState, position, 1.0f); 
mSession.setPlaybackState(stateBuilder.build()); 


private long getAvailableActions() { 


long actions - PlaybackState.ACTION PLAY | 
PlaybackState.ACTION PLAY FROM MEDIA ID | 
PlaybackState.ACTION PLAY FROM SEARCH; 

if (mPlayingQueue == null || mPlayingQueue.isEmpty()) 1 





return actions; 
} 
if (mState == PlaybackState.STATE_PLAYING) { 
actions |= PlaybackState.ACTION PAUSE; 
} 
if (mCurrentIndexOnQueue > 0) { 
actions |- PlaybackState.ACTION SKIP TO PREVIOUS; 
} 
if (mCurrentIndexOnQueue < mPlayingQueue.size() - 1) { 
actions |- PlaybackState.ACTION SKIP TO NEXT; 
} 


return actions; 


显示 媒体 元 数据 


为 当前 正在 播放 通过 setMetadata()) 方 法 设置 MediaMetadata 。. 这 个 方法 可 以 让 我 们 为 正在 
播放 卡 提供 有 关 轨 道 ， 如 标题 ， 副 标题 ， 和 各 种 图 标 等 信息 。 下 面 的 例子 假设 我 们 的 播放 数 
据 存 储 在 自 定义 的 MediaData 类 中 。 


private void updateMetadata(MediaData myData) { 

MediaMetadata.Builder metadataBuilder = new MediaMetadata.Builder(); 

// To provide most control over how an item is displayed set the 

// display fields in the metadata 

metadataBuilder.putString(MediaMetadata.METADATA KEY DISPLAY TITLE, 
myData.displayTitle); 

metadataBuilder.putString(MediaMetadata.METADATA KEY DISPLAY SUBTITLE, 
myData.displaySubtitle); 

metadataBuilder.putString(MediaMetadata.METADATA KEY DISPLAY ICON URI, 
myData.artUri); 

// And at minimum the title and artist for legacy support 

metadataBuilder.putString(MediaMetadata.METADATA KEY TITLE, 
myData.title); 

metadataBuilder.putString(MediaMetadata.METADATA KEY ARTIST, 
myData.artist); 

// ^ small bitmap for the artwork is also recommended 

metadataBuilder.putString(MediaMetadata.METADATA KEY ART, 
myData.artBitmap); 

// Add any other fields you have for your data as well 

mSession.setMetadata(metadataBuilder.build()); 


响应 用 户 的 动作 


当 用 户 选择 正在 播放 卡片 时 ,系统 打开 应 用 并 拥有 会 话 。 如 果 我 们 的 应 用 

在 setSessionActivity()) 有 Pendinglntent 要 传递 ,系统 将 会 像 下 面 演示 的 那样 开启 activity。 如 果 
不 是 ， 则 系统 默认 的 Intent 打 开 。 您 指定 的 活动 必须 提供 播放 控制 ， 允 许 用 户 暂 停 或 停止 播 
放 。 


Intent intent = new Intent(mContext, MyActivity.class); 
PendingIntent pi - PendingIntent.getActivity(context, 99 /*request code*/, 
intent, PendingIntent.FLAG UPDATE CURRENT); 
mSession.setSessionActivity(pi); 


帮助 用 户 在 TV 上 找到 内 容 


编写 :awong1900 - Æ x-:http://developer.android.com/training/tv/discovery/index.html 


TV 设备 为 用 户 提 供 了 许多 的 休闲 娱乐 选择 。 它 们 提供 上 千 个 应 用 和 相关 的 内 容 服务 。 同 时 ， 
大 部 分 用 户 操 作 TV 时 ， 喜 欢 比 较 少 的 输入 操作 。 面 对 用 户 可 能 的 选择 ， 重 要 的 一 点 是 应 用 开 
发 者 为 用 户 提供 快速 容易 的 路 径 ， 发 现 和 享受 我 们 的 内 容 。 


Android framework 层 帮助 我 们 为 用 户 提供 若干 路 径 ， 去 找到 内 容 ， 包 括 主屏 幕 的 推荐 和 应 用 
的 内 容 目 录 的 搜索 。 


这 节 课 展示 如 何 帮 助 用 户 找到 应 用 内 容 ， 通 过 推荐 和 应 用 内 搜索 。 
e 推荐 TV 内 容 学 习 如 何 推荐 内 容 给 用 户 ， 使 它 出 现在 TV 设备 的 主屏 幕 推 荐 栏 。 


e 使 TV 应 用 是 可 被 搜索 的 学 习 如 何 使 内 容 在 Android TV 主屏 幕 中 被 搜索 到 。 


e TV 应 用 内 搜索 学 习 如 何在 应 用 内 使 用 内 置 的 TV 搜索 界面 。 


推荐 TV 内 容 > 


> aR oe 
推荐 TV 内 容 
编写 :awong1900 - 原 
X :http://developer.android.com/training/tv/discovery/recommendations.html 


当 操 作 TV 时 ， 用 户 通常 喜欢 使 用 最 少 的 输入 操作 来 找 内 容 。 许 多 用 户 的 理想 场景 是 ， 坐 下 ， 
打开 TV 然后 观看 。 用 最 少 的 步骤 让 用 户 观 看 他 们 的 喜欢 的 内 容 是 最 好 的 方式 。 


Android framework 为 了 实现 较 少 交互 而 提供 了 主屏 幕 推荐 栏 。 在 设备 第 一 次 使 用 时 候 ， 内 容 
推荐 出 现在 TV 主屏 幕 的 第 一 栏 。 应 用 程序 的 内 容 目 录 提 供 推 荐 建议 可 以 把 用 户 带 回 到 我 们 的 


Stary Night 


Street View 





图 1. 一 个 推荐 栏 的 例子 


这 节 课 教 我 们 如 何 创 建 推荐 和 提供 他 们 到 Android framework， 这 样 用 户 能 容易 的 发 现 和 使 用 
我 们 的 应 用 内 容 。 这 个 讨论 描述 了 一 些 代 码 ， 在 Android Leanback 示 例 代 码 。 


创建 推荐 服务 


内 容 推荐 是 被 后 人 台 处 理 创 建 。 为 了 把 我 们 的 应 用 提供 到 内 容 推荐 ， 创 建 一 个 周期 性 添加 列表 
服务 ， 从 应 用 目录 到 系统 推荐 列表 。 


接 下 来 的 代码 描绘 了 如 何 扩展 IntentService 为 我 们 的 应 用 创建 推荐 服务 : 


public class UpdateRecommendationsService extends IntentService { 
private static final String TAG = "UpdateRecommendationsService"; 
private static final int MAX RECOMMENDATIONS - 3; 


public UpdateRecommendationsService() { 
super ("RecommendationService"); 


} 


@Override 
protected void onHandleIntent(Intent intent) { 


Log.d(TAG, "Updating recommendation cards"); 
HashMap<String, List<Movie>> recommendations = VideoProvider.getMovieList(); 
if (recommendations == null) return; 


int count = 0; 


try { 
RecommendationBuilder builder = new RecommendationBuilder() 
.setContext(getApplicationContext()) 
.setSmallIcon(R.drawable.videos by google icon); 


for (Map.Entry<String, List<Movie>> entry : recommendations.entrySet()) ( 
for (Movie movie : entry.getValue()) { 
Log.d(TAG, "Recommendation - " + movie.getTitle()); 


builder.setBackground(movie.getCardImageUrl()) 
.setId(count + 1) 
.setPriority(MAX RECOMMENDATIONS - count) 
.setTitle(movie.getTitle()) 
.setDescription(getString(R.string.popular header)) 
.setImage(movie.getCardImageUrl()) 
.setIntent(buildPendingIntent (movie)) 
.build(); 


if (++count >= MAX RECOMMENDATIONS) { 


break; 
T 
} 
if (++count >= MAX RECOMMENDATIONS) { 
break; 
} 


} 
catch (IOException e) { 


Log.e(TAG, "Unable to update recommendation", e); 


private PendingIntent buildPendingIntent(Movie movie) { 
Intent detailsIntent - new Intent(this, DetailsActivity.class); 
detailsIntent.putExtra("Movie", movie); 


TaskStackBuilder stackBuilder - TaskStackBuilder.create(this); 

stackBuilder.addParentStack(DetailsActivity.class); 

stackBuilder.addNextIntent(detailsIntent); 

// Ensure a unique PendingIntents, otherwise all recommendations end up with t 
he same 

// PendingIntent 

detailsIntent.setAction(Long.toString(movie.getId())); 


PendingIntent intent = stackBuilder.getPendingIntent(0, PendingIntent.FLAG UPD 
ATE CURRENT); 
return intent; 


使 服务 被 系统 意识 和 运行 ， 在 应 用 manifest 中 注册 它 ， 接 下 来 的 代码 片段 展示 了 如 何 定义 这 个 
类 做 为 服务 : 


«manifest ... > 
<application me 


«service 
android:name-"com.example.android.tvleanback.UpdateRecommendationsService" 
android:enabled-"true" /> 

«/application» 
«/manifest» 


刷新 推荐 


基于 用 户 的 行为 和 数据 来 推荐 ， 例 如 播放 列表 ， 喜 爱 列表 和 相关 内 容 。 当 刷新 推荐 时 ， 不 仅 
仅 是 删除 和 重新 加 载 他 们 ， 因 为 这 样 会 导致 推荐 出 现在 推荐 栏 的 结尾 。 一 旦 一 个 内 容 项 被 播 
放 ， 如 一 个 影片 ， 从 推荐 中 出 除 它 。 


应 用 的 推荐 顺序 被 保存 依据 应 用 提供 他 们 的 顺序 。framework interleave 应 用 推荐 基于 推荐 质 
量 ， 用 户 习惯 的 收集 。 最 好 的 推荐 应 是 推荐 最 合适 的 出 现在 列表 前 面 。 

~ ak 
创建 推荐 


一 旦 我 们 的 推荐 服务 开始 运行 ， 它 必须 创建 推荐 和 推送 他 们 到 Android framework 。 
Framework 收 到 推荐 作为 通知 对 象 。 它 用 特定 的 模板 并 且 标 记 为 特定 的 目录 。 


设置 值 


去 设置 推荐 卡片 的 UI 元 素 ， 创 建 一 个 builder 类 用 接 下 来 的 builder 样 式 描 述 。 首 先 ， 设 置 推荐 
卡片 元 素 的 值 。 


TV 上 的 推荐 内 容 


public class RecommendationBuilder { 


public RecommendationBuilder setTitle(String title) { 
mTitle - title; 
return this; 


public RecommendationBuilder setDescription(String description) { 
mDescription - description; 
return this; 


public RecommendationBuilder setImage(String uri) ( 
mImageUri - uri; 
return this; 


public RecommendationBuilder setBackground(String uri) { 
mBackgroundUri - uri; 
return this; 


创建 通知 


一 旦 我 们 设置 了 值 ， 然 后 去 创建 通知 ， 从 builder 类 分 配 值 到 通知 ， 并 且 调 
用 NotificationCompat.Builderbuild)。 


并 且 ， 确 信 调 用 setLocalOnly())， 这 样 NotificationCompat.BigPictureStyle 通 知 不 将 显示 在 另 


一 个 设备 。 


接 下 来 的 代码 示例 展示 了 如 何 创建 推荐 。 


6 


I 
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public class RecommendationBuilder { 
public Notification build() throws IOException { 


Notification notification - new NotificationCompat.BigPictureStyle( 

new NotificationCompat.Builder(mContext) 
.setContentTitle(mTitle) 
.setContentText(mDescription) 
.setPriority(mPriority) 
.setLocalonly(true) 
.setOngoing(true) 
.setColor(mContext.getResources().getColor(R.color.fastlane ba 

ckground)) 

.setCategory(Notification.CATEGORY RECOMMENDATION) 
. setLargeIcon(image) 
.setSmallIcon(mSmalllcon) 
.setContentIntent(mIntent) 
.setExtras(extras)) 

.build(); 


return notification; 


运行 推荐 服务 


我 们 的 应 用 推荐 服务 必须 周期 性 运行 确保 创建 当前 的 推荐 。 去 运行 我 们 的 服务 ， 创 建 一 个 类 
运行 计时 器 和 在 周期 间隔 关联 它 。 接 下 来 的 代码 例子 扩展 了 BroadcastReceiver 类 去 开始 每 半 
小 时 的 推荐 服务 的 周期 性 执行 : 


public class BootupActivity extends BroadcastReceiver ( 
private static final String TAG = "BootupActivity"; 


private static final long INITIAL DELAY - 5000; 


@Override 
public void onReceive(Context context, Intent intent) { 
Log.d(TAG, "BootupActivity initiated"); 
if (intent.getAction().endsWith(Intent.ACTION BOOT COMPLETED)) f 
scheduleRecommendationUpdate (context); 


private void scheduleRecommendationUpdate(Context context) { 
Log.d(TAG, "Scheduling recommendations update"); 


AlarmManager alarmManager - (AlarmManager) context.getSystemService(Context.AL 


ARM SERVICE); 
Intent recommendationIntent - new Intent(context, UpdateRecommendationsService 


.class); 
PendingIntent alarmIntent - PendingIntent.getService(context, 0, recommendatio 


nIntent, ©); 


alarmManager.setInexactRepeating(AlarmManager.ELAPSED REALTIME WAKEUP, 
INITIAL DELAY, 
AlarmManager.INTERVAL HALF HOUR, 
alarmIntent); 


这 个 BroadcastReceiver 类 的 实现 必须 运行 在 TV 设备 启动 后 。 为 了 完成 这 个 ， 注 册 这 个 类 在 
应 用 manifest 的 intet filter 中 ， 它 监听 设备 启动 完成 。 接 下 来 的 代码 展示 了 如 何 添加 这 个 配置 到 


manifest ° 


«manifest ... > 
<sappilicacron e 
«receiver android:name-"com.example.android.tvleanback.BootupActivity" 
android:enabled-"true" 
android:exported-"false"» 
<intent-filter> 
<action android:name="android.intent.action.BOOT_COMPLETED"/> 
</intent-filter> 
</receiver> 
</application> 
</manifest> 


Important : 接收 一 个 启动 完成 通知 需要 我 们 的 应 用 有 RECEIVE_BOOT_COMPLETED 
权限 。 更 多 信息 ， 查 看 ACTION_BOOT_COMPLETED ° 


在 推荐 服务 类 的 onHandlelntent()) 方 法 中 ， 用 以 下 代码 提交 推荐 到 管理 器 : 


Notification notification = notificationBuilder.build(); 
mNotificationManager.notify(id, notification); 


下 一 节 : 使 TV 应 用 是 可 被 搜索 的 > 


使 TV 应 用 是 可 被 搜索 的 


编写 :awong1900 - 原 


X :http://developer.android.com/training/tv/discovery/searchable.html 


Android TV 使 用 Android 搜 索 接 口 从 安装 的 应 用 中 检索 内 容 数 据 并 且 释 放 搜 索 结果 给 用 户 。 我 
们 的 应 用 内 容 数 据 能 被 包含 在 这 些 结果 中 ， Hr dd iode qan d) o 


我 们 的 应 用 必须 提供 Android TV 数据 字段 ， 它 是 用 户 在 搜索 框 中 输入 字符 生成 的 建议 搜索 结 
果 。 去 做 这 个 ， 我 们 的 应 用 必须 实现 Content Provider， 在 searchable.xml 配 置 文件 描述 


content provider 和 其 他 必要 的 Android TV 信息 。 
的 搜索 结果 时 处 理 intent 的 触发 。 所 有 的 这 


3t Android TV 应 用 搜索 的 关键 点 。 


我 们 也 需要 一 个 activity 在 用 户 选择 一 个 建议 
些 被 描述 在 Adding Custom Suggestions。 本 文 描 


这 节 课 展示 Android 中 搜索 的 知识 ， 展 示 如 何 使 我 们 的 应 用 在 Android TV 里 是 可 被 搜索 的 。 确 


信 我 们 熟悉 Search API guide 的 解释 。 在 下 面 的 这 


Functionality 训 练 课程 。 


节 课 程 之 前 ， 查 看 Adding Search 


个 讨论 描述 的 一 些 代 码 ， 从 Android Leanback 示 例 代 码 摘 出 。 代 码 可 以 在 Github 上 找到 。 


识别 列 


SearchManager 描 述 了 数据 字段 ， 它 被 代表 为 SQLite 数 据 库 的 列 。 不 管 我 们 的 数据 格式 ， 我 


们 必须 把 我 们 的 数据 字段 境 到 那些 列 ， 通 


看 Building a suggestion table() ° 


SearchManager 类 为 AndroidTV 包 含 了 几 个 列 


值 
SUGGEST COLUMN TEXT 1 
SUGGEST COLUMN TEXT 2 


SUGGEST COLUMN RESULT. CARD IMAGE 





SUGGEST COLUMN CONTENT TYPE 


SUGGEST COLUMN VIDEO WIDTH 





SUGGEST COLUMN VIDEO HEIGHT 





SUGGEST COLUMN PRODUCTION YEAR 


SUGGEST. COLUMN. DURATION 


常用 存 取 我 们 的 内 容 数 据 的 类 。 更 多 信息 ， 查 


。 下面 是 重要 的 一 些 列 : 


首 述 

内 容 名 字 (必须 ) 

内 容 的 文本 描述 
图 片 /封面 
媒体 的 MIME 类 型 (必须 ) 


媒体 的 分 辨 率 宽 度 


媒体 的 分 辨 率 高 度 
内 容 的 产品 年 份 (必须 ) 


媒体 的 时 间 长 度 


搜索 framework 需 要 以 下 的 列 : 


e SUGGEST COLUMN TEXT 1 
e SUGGEST COLUMN CONTENT. TYPE 
e SUGGEST COLUMN PRODUCTION YEAR 


当 这 些 内 容 的 列 的 值 匹配 Google 服 务 的 providers 提 供 的 的 值 时 ， 系 统 提 供 一 个 深 链接 到 我 们 
的 应 用 ， 用 于 详情 查看 ， 以 及 指向 应 用 的 其 他 Providers 的 链接 。 更 多 讨论 在 在 详情 页 显示 内 


Ge 


Ae 


7| 


我 们 的 应 用 的 数据 库 类 可 能 定义 以 下 的 列 : 


public class VideoDatabase { 
//The columns we'll include in the video database table 
public static final String KEY NAME - SearchManager.SUGGEST COLUMN TEXT 1; 
public static final String KEY DESCRIPTION - SearchManager.SUGGEST COLUMN TEXT 2; 
public static final String KEY ICON - SearchManager.SUGGEST COLUMN RESULT CARD IMAGE 





public static final String KEY DATA TYPE = SearchManager.SUGGEST COLUMN. CONTENT TYPE 


public static final String KEY IS LIVE - SearchManager.SUGGEST COLUMN IS LIVE; 
public static final String KEY VIDEO WIDTH - SearchManager.SUGGEST COLUMN VIDEO WIDT 





H; 

public static final String KEY VIDEO HEIGHT - SearchManager.SUGGEST COLUMN VIDEO HEI 
GHT; 

public static final String KEY AUDIO CHANNEL CONFIG - 

SearchManager.SUGGEST COLUMN AUDIO CHANNEL CONFIG; 

public static final String KEY PURCHASE PRICE - SearchManager.SUGGEST COLUMN PURCHAS 
E PRICE; 

public static final String KEY RENTAL PRICE - SearchManager.SUGGEST COLUMN RENTAL PR 
ICE; 

public static final String KEY RATING STYLE - SearchManager.SUGGEST COLUMN RATING ST 
YLE; 

public static final String KEY RATING SCORE - SearchManager.SUGGEST COLUMN RATING SC 
ORE; 

public static final String KEY PRODUCTION YEAR - SearchManager.SUGGEST COLUMN PRODUC 
TION YEAR; 

public static final String KEY COLUMN DURATION - SearchManager.SUGGEST COLUMN DURATI 
ON; 

public static final String KEY ACTION - SearchManager.SUGGEST COLUMN INTENT ACTION; 




















当 我 们 创建 从 SearchManager 列 填充 到 我 们 的 数据 字段 时 ， 我 们 也 必须 定义 ID 去 获得 每 行 的 
独一无二 的 ID 。 


private static HashMap buildColumnMap() { 
HashMap map - new HashMap(); 
map.put(KEY NAME, KEY NAME); 
map.put(KEY DESCRIPTION, KEY DESCRIPTION); 
map.put(KEY ICON, KEY ICON); 
map.put(KEY. DATA TYPE, KEY. DATA TYPE); 
map.put(KEY IS LIVE, KEY IS LIVE); 
map.put(KEY VIDEO WIDTH, KEY VIDEO WIDTH); 
map.put(KEY VIDEO HEIGHT, KEY VIDEO HEIGHT); 
map.put(KEY AUDIO CHANNEL CONFIG, KEY AUDIO CHANNEL CONFIG); 
map.put(KEY PURCHASE PRICE, KEY PURCHASE PRICE); 
map.put(KEY RENTAL PRICE, KEY RENTAL PRICE); 
map.put(KEY RATING STYLE, KEY RATING STYLE); 
map.put(KEY RATING SCORE, KEY RATING SCORE); 
map.put(KEY PRODUCTION YEAR, KEY PRODUCTION YEAR); 
map.put(KEY COLUMN DURATION, KEY COLUMN DURATION); 
map.put(KEY ACTION, KEY ACTION); 
map.put(BaseColumns. ID, "rowid AS " + 
BaseColumns. ID); 
map.put(SearchManager.SUGGEST COLUMN INTENT DATA ID, "rowid AS " + 
SearchManager.SUGGEST COLUMN INTENT DATA ID); 
map.put(SearchManager.SUGGEST COLUMN SHORTCUT ID, "rowid AS " + 
SearchManager.SUGGEST COLUMN SHORTCUT ID); 
return map; 








在 上 面 的 例子 中 ， 注 意 填充 SUGGEST_COLUMN INTENT DATA ID Rt » 3x 
作 ， 指 向 独一无二 的 内 容 到 这 一 列 的 数据 ， 那 是 URI 描 述 的 内 容 被 存储 的 最 后 于 
第 一 部 分 ， 与 所 有 表格 的 列 同样 ， 是 设置 在 searchable.xml 文 件 ， 

用 android:searchSuggestlntentData 属 性 。 属 性 被 描述 在 Handle Search Suggestions 。 


是 URI 的 一 部 
后 部 分 。 在 URI 的 


如 果 URI 的 第 一 部 分 是 不 同 ne > 我 们 填充 SUGGEST_COLUMN INTENT DATA 
字段 的 值 。 当 用 户 选 择 这 个 内 容 时 ， 这 个 intent 被 启动 依 

据 SUGGEST_COLUMN_INTENT_DATA ID 的 混合 intent 数 据 或 

者 android:searchsuggestIntentData 属性 和 SUGGEST_COLUMN_INTENT_DATA 字 段 值 之 


— o 


提供 搜索 建议 数据 


实现 一 个 Content Provider 去 返回 搜索 术语 建议 到 AndroidTV 搜 索 框 。 系 统 需 要 我 们 的 内 容 容 
器 提供 建议 ， 通 过 调用 每 次 一 个 字母 类 型 query()) 方 法 。 在 query()) 的 实现 中 ， 我 们 的 内 容 容 
器 搜索 我 们 的 建议 数据 并 且 返 回 一 个 光标 指向 我 们 已 经 指定 的 建议 列 。 


@Override 
public Cursor query(Uri uri, String[] projection, String selection, String[] selecti 
onArgs, 
String sortOrder) { 

// Use the UriMatcher to see what kind of query we have and format the db query ac 
cordingly 

switch (URI_MATCHER.match(uri)) { 

case SEARCH_SUGGEST: 


Log.d(TAG, "search suggest: " + selectionArgs[0] + " URI: " + uri); 
if (selectionArgs == null) { 
throw new IllegalArgumentException( 
"selectionArgs must be provided for the Uri: " + uri); 
} 
return getSuggestions(selectionArgs[0]); 
default: 


throw new IllegalArgumentException("Unknown Uri: " + uri); 


private Cursor getSuggestions(String query) { 
query - query.toLowerCase(); 
new String[]{ 


String[] columns - 


BaseColumns. ID, 
VideoDatabase.KEY NAME, 


}; 


VideoDatabase. 
VideoDatabase. 
VideoDatabase. 
VideoDatabase. 
VideoDatabase. 
VideoDatabase. 
VideoDatabase. 
VideoDatabase. 
VideoDatabase. 
VideoDatabase. 
VideoDatabase. 
VideoDatabase. 
VideoDatabase. 
VideoDatabase. 


SearchManager 


KEY DESCRIPTION, 

KEY ICON, 

KEY DATA TYPE, 

KEY IS LIVE, 

KEY VIDEO WIDTH, 

KEY VIDEO HEIGHT, 
KEY AUDIO CHANNEL CONFIG, 
KEY PURCHASE PRICE, 
KEY RENTAL PRICE, 
KEY RATING STYLE, 
KEY RATING SCORE, 
KEY PRODUCTION YEAR, 
KEY. COLUMN DURATION, 
KEY. ACTION, 


.SUGGEST. COLUMN INTENT DATA ID 





return mVideoDatabase.getWordMatch(query, columns); 


B > ua 


在 我 们 的 manifest 文 件 中 ， 内 容 容器 接受 特殊 处 理 。 相 比 被 标记 为 一 个 activity， 它 是 被 描述 为 
[provider](http://developer.android.com/guide/topics/manifest/provider-element.html) ° 
provider &,4& android:searchsuggestAuthority 属性 去 告诉 系统 我 们 的 内 容 容器 的 名 字 空 间 。 
并 且 ， 我 们 必须 设置 它 的 android:exported ATEX "true" ， 这 样 Android 全 局 搜索 能 用 它 返 


回 的 搜索 结果 。 


«provider android:name="com.example.android.tvleanback.VideoContentProvider" 
android:authorities-"com.example.android.tvleanback" 
android:exported="true" /> 


处 理 搜索 建议 


我 们 的 应 用 必须 包括 res/xml/searchable.xml 文 件 去 配置 搜索 建议 设置 。 它 包括 
android:searchSuggestAuthority 属 性 去 告诉 系统 内 容 容器 的 名 字 空 间 。 这 必须 匹配 
在 AndroidManifest.xml 文件 的 [provider] 
(http://developer.android.com/guide/topics/manifest/provider-element.html) 元 素 的 
android:authorities 属性 的 字符 串 值 。 


searchable.xml 文 件 必须 也 包含 在 "android.intent.action.VIEW" 的 
android:searchSuggestlntentAction 值 去 定义 提供 自 定义 建议 的 intent action。 这 与 提供 一 个 
搜索 术语 的 intent action 不 同 ， 下 面 解释 。 查 看 Declaring the intent action 用 另 一 种 方式 去 定 
义 建 议 的 intent action ° 


同 intent action 一 起 ， 我 们 的 应 用 必须 提供 我 们 定义 的 android:searchSuggestlntentData 属 性 
的 intent 数 据 。 这 是 指向 内 容 的 URI 的 第 一 部 分 。 它 描述 在 填充 的 内 容 表格 中 URI 所 有 共同 列 的 
部 分 。URI 的 独一无二 的 部 分 用 SUGGEST_COLUMN_INTENT_DATA_ID 字 段 建 立 每 一 列 ， 
以 上 被 描述 在 识别 列 。 查 看 Declaring the intent data 用 另 一 种 方式 去 定义 建议 的 intent 数 据 。 


并 且 ， 注 意 android:searchsuggestSelection="?" 属性 为 特定 的 值 。 这 个 值 作为 query()) 方 
法 selection 参数 。 方 法 的 问题 标记 (?) 值 被 代替 为 请 求 文本 。 


最 后 ， 我 们 也 必须 包含 android:includelnGlobalSearch 属 性 值 为 "true" 。 这 是 一 
^*searchable.xml xX £F & 45] F : 


«searchable xmlns:android-"http://schemas.android.com/apk/res/android" 
android:label-"Qstring/search label" 
android:hint-z"Qstring/search hint" 
android:searchSettingsDescription-"Qstring/settings description" 
android:searchSuggestAuthority-"com.example.android.tvleanback" 
android:searchSuggestIntentAction-"android.intent.action.VIEW" 
android:searchSuggestIntentData-"content://com.example.android.tvleanback/vide 
o database leanback" 
android:searchSuggestSelection-" ?" 
android: searchSuggestThreshold="1" 
android: includeInGlobalSearch="true" 
> 


</searchable> 


处 理 搜索 术语 


使 得 TV App 能 够 被 搜索 


一 旦 搜索 框 有 一 个 字 匹 配 到 了 应 用 列 中 的 一 个 (被 描述 在 上 文 的 识别 列 ) ， 系 统 启动 
ACTION SEARCH intent。 我 们 应 用 的 activity 处 理 intent 搜 索 列 的 给 定 的 字段 资源 ， 并 且 返 回 
一 个 那些 内 容 项 的 列表 。 在 我 们 的 AndroidManifest .xml 文件 中 ， 我 们 指定 的 activity 处 

理 ACTION_SEARCH intent， 像 这 样 : 


«activity 
android:namez"com.example.android.tvleanback.DetailsActivity" 
android:exported="true"> 


<!-- Receives the search request. --> 
<intent-filter> 
<action android:name="android.intent.action.SEARCH" /> 
<!-- No category needed, because the Intent will specify this class componen 


</intent-filter> 


<!-- Points to searchable meta data. --> 
<meta-data android:name="android.app.searchable" 
android: resource="@xml/searchable" /> 
</activity> 


<!-- Provides search suggestions for keywords against video meta data. --> 

<provider android:name="com.example.android.tvleanback.VideoContentProvider" 
android: authorities="com.example.android.tvleanback" 
android:exported="true" /> 


activity 必 须 参 考 searchable.xml 文 件 描述 可 搜索 的 设置 。 用 全 局 搜索 框 ，manifest 必 须 描述 
activity 应 该 收 到 的 搜索 请 求 。manifest 必 须 描述 [provider] 
(http://developer.android.com/guide/topics/manifest/provider-element.html) 元 素 ， 详 细 被 描述 
在 searchable.xml 文 件 。 


深 链接 到 应 用 的 详情 页 


如 果 我 们 有 设置 处 理 搜 索 建议 描述 的 搜索 配置 和 卉 充 

SUGGEST COLUMN TEXT. 1» SUGGEST_COLUMN_CONTENT_TYPE## 
SUGGEST_COLUMN_PRODUCTION_YEAR 字 段 到 识别 列 ， 一 个 深 链 接 去 查看 详情 页 的 内 
容 。 当 用 户 选 择 一 个 搜索 结果 时 ， 详 情 页 将 打开 。 如 图 1。 


使 得 TV App 能 够 被 搜索 


Sintel 


2010 ik © ioo? 


2010  Fantasy/Short Film - Oh 15m - Sintel follows the story of a girl 
named Sintel searching for a baby dragon 
6 copyright Blender Foundation | www.sintel.org 


8 AVAILABLE cm AVAILABLE ON 
ON GOOGLE PLAY MOVIES & TV VIDEOS BY GOOGLE 





> | Ghat: ™® 
图 1 详情 页 显示 一 个 深 链 接 为 Google(Leanback) 的 视频 代码 。Sintel: © copyright Blender 
Foundation, www.sintel.org. 









当 用 户 选 择 我 们 的 应 用 链接 ， "available on” 按钮 被 标识 在 详情 页 ， 系 统 启 动 activity 处 
XZACTION VIEW (在 searchable.xml 文 件 设 置 android:searchSuggestintentAction 值 

为 "android.intent.action.VIEW" ) ° 

我 们 也 能 设置 用 户 intent 去 启动 我 们 的 activity， 这 个 在 在 AndroidLeanback 示 例 代 码 应 用 中 演 
Too 注意 示例 应 用 启动 它 自己 的 LeanbackDetailsFragment 去 显示 被 选择 媒体 的 详情 ， 但 是 我 
们 应 该 启动 activity 去 播放 媒体 。 立 即 去 保存 用 户 的 另 一 次 或 两 次 点 击 。 


下 一 节 : 使 TV 应 用 是 可 被 搜索 的 > 


684 


TV 应 用 内 搜索 


编写 :awong1900 - 原文 :http://developer.android.com/training/tv/discovery/in-app- 
search.html 


当 在 TV 上 用 媒体 应 用 时 ， 用 户 脑 中 通常 有 期 望 的 内 容 。 如 果 我 们 的 应 用 包含 一 个 大 的 内 容 目 
录 ， 为 用 户 找到 他 们 想 找 到 的 内 容 时 ， 用 特定 的 标题 浏览 可 能 不 是 最 有 效 的 方式 。 一 个 搜索 
界面 能 帮助 用 户 获得 他 们 想 快速 浏览 的 内 容 。 


Leanback support library 提 供 一 套 类 库 去 使 用 标准 的 搜索 界面 。 在 我 们 的 应 用 内 使 用 类 库 ， 
可 以 和 TV 其 他 搜索 功能 ， 如 语音 搜索 ， 获 得 一 致 性 。 


这 节 课 讨论 如 何在 我 们 的 应 用 中 用 Leanback 支 持 类 库 提供 搜索 界面 。 


添加 搜索 操作 


当 我 们 用 BroweseFragment 类 做 一 个 媒体 浏览 界面 时 ， 我 们 能 使 用 搜索 界面 作为 用 户 界 面 的 
一 个 标准 部 分 。 当 我 们 设置 View.OnClickListener 在 BrowseFragment 对 象 时 ， 搜 索 界 面 作为 
一 个 图 标 出 现在 布局 中 。 接 下 来 的 示例 代码 展示 了 这 个 技术 。 


@Override 

public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.browse activity); 


mBrowseFragment = (BrowseFragment ) 
getFragmentManager( ).findFragmentById(R.id.browse fragment); 


mBrowseFragment.setOnSearchClickedListener(new View.OnClickListener() { 
@Override 
public void onClick(View view) { 
Intent intent = new Intent(BrowseActivity.this, SearchActivity.class); 
startActivity(intent); 
} 
}); 


mBrowseFragment.setAdapter(buildAdapter()); 


**Note**: You can set the color of the search icon using the setSearchAffordanceColor(int).-- 


> 


Note : 我 们 能 设置 搜索 图 标的 颜色 用 setSearchAffordanceColorkint))。 


添加 搜索 输入 和 结果 展示 


当 用 户 选择 搜索 图 标 ， 系 统 通过 定义 的 intent 关 联 一 个 搜索 activity。 我 们 的 搜索 activity 应 该 用 
包括 SearchFragment 的 线性 布局 。 这 个 fragment 必 须 实现 
SearchFragment.SearchResultProvider 界 面 去 显示 搜索 结果 。 


接 下 来 的 示例 代码 展示 了 如 何 扩展 SearchFragment 类 去 提供 搜索 界面 和 结果 : 


public class MySearchFragment extends SearchFragment 
implements SearchFragment.SearchResultProvider { 


private static final int SEARCH DELAY MS = 300; 
private ArrayObjectAdapter mRowsAdapter; 
private Handler mHandler - new Handler(); 
private SearchRunnable mDelayedLoad; 


@Override 
public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 


mRowsAdapter - new ArrayObjectAdapter(new ListRowPresenter()); 
setSearchResultProvider(this); 
setOnItemClickedListener(getDefaultItemClickedListener()); 
mDelayedLoad - new SearchRunnable(); 


@Override 
public ObjectAdapter getResultsAdapter() { 
return mRowsAdapter; 


QOverride 
public boolean onQueryTextChange(String newQuery) ( 
mRowsAdapter.clear(); 
if (!TextUtils.isEmpty(newQuery)) 1 
mDelayedLoad.setSearchQuery(newQuery); 
mHandler.removeCallbacks(mDelayedLoad); 
mHandler.postDelayed(mDelayedLoad, SEARCH DELAY MS); 


} 

return tnue,; 
} 
@Override 


public boolean onQueryTextSubmit(String query) { 
mRowsAdapter.clear(); 
if (!TextUtils.isEmpty(query)) { 
mDelayedLoad.setSearchQuery(query); 
mHandler.removeCallbacks(mDelayedLoad); 
mHandler.postDelayed(mDelayedLoad, SEARCH DELAY MS); 
} 


neturmtrue, 


上 面 的 示例 代码 展示 了 在 分 开 的 线程 用 独立 的 searchRunnable 类 去 运行 搜索 请 求 。 这 个 技巧 
是 从 正在 阻塞 的 主线 程 保 持 了 潜在 的 慢 运行 请 求 。 


使 用 TV 应 用 进行 搜索 


下 一 节 : 创建 TV 游戏 应 用 > 


688 


创建 TV 游戏 应 用 


编写 :dupengwei - /$ xc :http://developer.android.com/training/tv/games/index.html 


TV 屏幕 为 手机 游戏 开发 者 提供 了 大 量 的 新 思考 。 这 些 领域 包括 它 的 大 尺寸 ， 它 的 控制 方案 和 
所 有 玩家 可 以 同时 观看 的 事实 。 


开发 TV 游戏 时 有 两 点 要 记 住 ， 就 是 TV 屏幕 具有 共享 显示 器 的 特性 ， 和 横向 设计 游戏 的 需求 。 


考虑 共享 显示 


客厅 TV 带 来 了 多 人 游戏 的 设计 挑战 ， 客 厅 TV 游 戏 时 所 有 玩家 都 可 以 看 到 。 这 个 问题 与 游戏 ， 
特别 是 依靠 每 个 玩家 用 于 隐藏 信息 的 游戏 (如 纸牌 游戏 、 战 略 游戏 ) 息息相关 。 我 们 可 以 通 
过 实现 一 些 机 制 来 解决 一 个 玩家 窃取 另 一 玩家 信息 的 问题 。 这 些 机 制 是 : 


。 屏幕 日 可 以 帮助 隐藏 信息 。 例 如 ， 在 一 个 回合 制 游戏 ， 像 单词 或 卡片 游戏 ,一 次 只 有 一 
个 玩家 能 看 到 显示 的 内 容 。 当 这 个 玩家 完成 一 个 步 又， 游戏 允许 他 用 一 个 能 阻碍 其 他 人 
看 到 秘密 信息 的 覃 庶 住 屏幕 。 当 下 一 个 玩家 开始 操作 ， 这 个 覃 就 会 打开 显示 他 自己 的 信 
go 


AX 


e 在 手机 或 平板 电脑 上 运行 一 个 伙伴 app 作 为 第 二 屏幕 ， 通 过 这 种 方式 让 玩家 隐藏 信息 。 


支持 横向 显示 
TV 总 是 单 向 显示 的 : 我 们 不 能 翻转 它 的 屏幕 ， 且 没有 纵向 显示 。 要 总 是 以 横向 显示 模式 设计 
我 们 的 TV 游戏 。 


输入 设备 


TV 没有 触摸 屏 接口 ， 所 以 更 重要 的 是 获取 控制 要 正确 ， 并 确保 玩家 使 用 起 来 要 直观 和 有 趣 。 
处 理 控制 器 还 介绍 了 其 他 一 些 问 题 需要 注意 ， 如 跟踪 多 个 控制 器 ，， 处 理 断 开 要 适当 。 


支持 D-pad 控制 


围绕 方向 键 (D-pad) 控制 来 计划 我 们 的 控制 方案 ， 因 为 这 种 控制 是 Android TV 设备 的 默认 设 
置 。 玩 家 需要 在 游戏 的 所 有 方面 使 用 方向 键 (D-pad) 不 仅仅 是 控制 核心 游戏 设置 ， 而 且 
能 导航 菜单 和 广告 。 因 此 ， 我 们 还 应 该 确保 我 们 的 Android TV 游戏 不 能 涉及 触摸 屏 。 例 如 ， 





一 个 Android TV 游戏 不 应 该 告诉 玩家 > 点 击 这 里 继续 。 如 何 塑 造 玩家 使 用 控制 器 与 游戏 进 
互动 的 方式 将 是 实现 良好 用 户 体验 的 关键 : 


e 通信 控制 器 的 要 求 。 利 用 Android 市 场 上 app 的 产品 描述 将 控制 器 的 期 望 传达 给 玩家 们 。 
如 果 一 个 游戏 使 用 摇 杆 游戏 手柄 比 只 用 一 个 方向 键 更 合适 ， 请 将 这 一 事实 说 清楚 。 玩 家 
使 用 一 个 不 适合 游戏 的 控制 器 玩 游戏 很 可 能 导致 游戏 体验 欠 佳 ， 从 而 对 游戏 的 评价 造成 
不 利 影响 。 

。 使 用 一 致 的 按钮 映射 。 直 观 和 灵活 的 按钮 映射 是 良好 用 户 体验 的 关键 。 例 如 ， 我 们 应 该 
遵守 使 用 A 按 钮 接受 ， no 的 既定 习惯 。 我 们 也 可 以 提供 重 映射 形式 方面 的 灵活 
性 。 的 更 多 信 ， nl Controller Actions ° 

e 检测 控制 器 功能 并 相应 mm 。 查询 控制 器 的 能 力 以 优化 控制 器 和 游戏 直接 的 匹配 程 
度 。 例 如 ， 我 们 可 能 打算 让 一 个 玩家 通 过 接 是 控制 器 来 控制 一 个 对 象 。 然 而 ， 如 果 玩 家 
的 控制 器 缺少 加 速 计 和 陀螺 仪 硬件 设施 ， 摇 晃 控 制 器 并 不 会 产生 效果 。 所 以 ， 我 们 的 游 
戏 应 该 检查 控制 器 ， 器 不 支持 运行 检测 ， 则 切换 到 另 一 个 可 用 的 控制 方案 。 
更 多 关于 检测 控制 器 功能 的 信息 ， 参 见 Controllers Across Android Versions ° 


提供 适当 的 后 退 按钮 的 行为 


返回 按钮 不 应 该 作为 切换 。 例 如 ， 不 能 使 用 它 打 开 和 关闭 一 个 菜单 。 它 应 该 只 能 导航 后 退 ， 
breadcrumb-style， 玩 家 之 前 访问 过 屏幕 页 面 ， 例 如 : 游戏 界面 > 游戏 暂停 界面 > 游戏 主 界面 
>Android 主 界面 。 由 于 返回 按钮 应 该 只 能 进行 线性 导航 (后 退 ) ， 我 们 可 以 使 用 返回 按钮 离 
开 一 个 游戏 内 菜单 (由 不 同 的 按钮 打开 ) ， 回 到 a 更 多 关于 导航 设计 的 信息 ， 参 见 
Navigation with Back and Up ° 学习 更 多 关于 实现 的 信息 ， 参 见 Providing Proper Back 
Navigation ° 


使 用 适当 的 按钮 


并 不 是 所 有 的 游戏 控制 器 提供 开始 ,搜索 ,或 菜单 按钮 。 确 保 我 们 的 UI 不 取决 于 这 些 按 钮 的 使 
用 o 


处 理 多 个 控制 器 


当 多 个 玩家 玩 游戏 ,每 个 都 有 他 或 她 自 "ie 器 ， 做 好 每 对 “玩家 -控制 器 "的 映射 是 很 重要 
的 。 关 于 如 何 实现 "控制 器 -数量 ”识别 的 信息 ， 参 见 Input Devices » 


处 理 控制 器 的 断 开 


当 控 制 器 从 游戏 中 断 开 时 ， 游 戏 应 该 暂停 ， 并 弹出 一 个 对 话 框 促使 断 开 的 玩家 重新 连接 他 或 
她 的 控制 器 。 对 话 框 还 应 提供 排除 故障 的 提示 (如 ， 一 个 弹出 的 对 话 框 告诉 玩家 “检查 我 们 的 
蓝牙 连接 ") 关于 实现 输入 设备 支持 的 更 多 信息 ,参见 Handling Controller Actions。 具 体 关 于 蓝 
牙 连接 的 信息 ， 参 见 Bluetooth » 


展示 控制 器 说 明 


如 果 我 们 的 游戏 提供 了 可 视 化 的 游戏 控制 说 明 ， 控 制 器 图 片 应 该 是 免费 的 、 品 牌 化 的 ， 并 且 
只 能 包含 与 Android 兼 容 的 按钮 。 mw a et ， 点击 Android TV Gamepad 
Template (ZIP) 下 载 。 它 包含 一 个 黑 底 的 白色 控制 器 和 一 个 白 底 的 黑色 控制 器 ， 是 一 个 PNG 类 
型 的 Adobe®@lllustrator®@ 文 件 。 
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Figure 1. 控制 器 说 明 的 示例 请 使 用 Android TV Gamepad Template (ZIP) 


Manifest 
有 一 些 特殊 的 东西 应 该 包含 在 游戏 的 Android Manifest 里 。 
在 屏幕 主 界面 显示 游戏 


Android TV 主 界 面 采 用 单独 一 行 来 显示 游戏 ， 与 常规 应 用 分 开 显 示 。 为 了 让 游戏 出 现在 游戏 
列表 ， 设 置 游戏 的 manifest 清 单 的 标签 下 的 android:iscame 属性 为 "true" 。 例 如 : 


«application 


android:isGame-"true" 


声明 游戏 控制 器 支持 
游戏 控制 器 对 于 TV 设备 的 用 户 uM o M o n 了 适当 的 通知 用 户 ， 游 戏 需 要 (或 只 
支持 ) 一 个 控制 器 ， 我 们 必须 在 app 的 manifest 里 包含 这 些 条 目 。 如 果 我 们 需要 一 个 游戏 控制 
器 ， 我 们 必须 在 app 的 manifest 中 包含 以 下 条 目 : 


<uses-feature android:name="android.hardware.gamepad"/> 


如 果 我 们 的 游戏 使 用 了 一 个 游戏 控制 器 ， 但 是 不 需要 ， 在 app 的 manifest 里 包含 以 下 的 功能 条 
H3 


«uses-feature android:name-"android.hardware.gamepad" android:required-"false"/» 


更 多 关于 manifest 条 目的 信息 ， 参 见 App Manifest » 


Google Play Game 服务 


如 果 我 们 的 游戏 集成 了 Google Play Game 服务 ， 我 们 应 该 记 住 一 些 关 于 成 果 的 注意 事项 ， 登 
录 ， 保 存 游戏 ， 和 多 人 游戏 。 


我 们 的 游戏 应 包含 至 少 5 个 (可 获取 的 ) 成 果 。 只 有 一 个 用 户 从 一 个 受 支持 的 输入 设备 控制 游戏 
应 该 能 够 获得 成 就 。 关 于 成 就 的 更 多 信息 以 及 如 何 实现 ， 参 见 Achievements in Android ° 


NS 


我 们 的 游戏 应 该 试图 在 启动 的 时 候 让 用 户 登 录 。 如 果 玩 家 连续 几 次 拒绝 登录 后 ， 游 戏 应 该 停 
止 询问 。 学 习 更 多 关于 登录 的 信息 在 Implementing Sign-in on Android ° 


保存 


使 用 Google Play Services 保 存 游 戏 来 存储 保存 的 游戏 。 我 们 应 该 讲 保存 的 游戏 绑 定 到 一 个 特 
定 的 谷歌 账号 ， 作 为 唯一 标识 ， 甚 至 在 跨 设 备 时 也 不 受 影 响 。 无 论 玩家 使 用 手机 或 TV， 游 戏 
应 该 可 以 从 同一 个 用 户 账 号 获取 到 保存 的 游戏 信息 。 


我 们 也 应 该 在 我 们 的 游戏 的 U 提 供 一 个 选项 ,让 玩家 删除 本 地 和 云 存 储 端的 数据 。 我 们 可 能 把 
选项 放 在 游戏 的 设置 界面 。 使 用 Play Services 保 存 游 戏 的 实现 细节 ， 参 见 Saved Games in 
Android 


乡 人 游戏 


一 个 游戏 要 提供 多 人 游戏 体验 ， 必 须 允 许 至 少 2 个 玩家 进入 一 个 房间 。 进 一 步 了 解 Android 的 
多 人 游戏 信息 ， 参 见 Android developer 网 站 的 Real-time Multiplayer 和 Turn-based Multiplayer 
文档 。 


退出 


提供 一 个 一 臻 和 明显 的 UI 元 素 , 让 用 户 适 当 的 退出 游戏 。 这 个 元 素 应 该 用 方向 键 导航 按钮 访 
问 ， 这 样 做 而 不 是 依赖 Home 键 提供 退出 功能 ， 是 因为 在 使 用 不 同 的 控制 器 时 ， 若 依赖 Home 
键 提供 退出 功能 ， 这 既 不 一 致 也 不 可 靠 。 


Web 


不 要 让 android TV 的 游戏 浏览 网 页 。Android TV 不 支持 web 浏 览 器 。 
Note : 我 们 可 以 使 用 WebView 类 实现 登录 像 Google+ 和 Facebook 这 样 的 服务 。 
网 络 
游戏 经 常 需要 更 大 的 带宽 提供 最 佳 的 性 能 ,许多 用 户 宁愿 选择 有 线 网 而 不 愿 选择 WiFi 来 提供 性 


能 。 我 们 的 app 应 该 对 有 线 网 和 WiFi 连 接 都 进行 检查 。 如 果 我 们 的 app 只 针对 TV， 我 们 不 需要 
检查 3G/LTE 服 务 ， 而 移动 app 则 需要 检查 3G/LTE 服 务 。 


下 一 节 : TV 应 用 清单 > 


创建 TV 直播 应 用 


编写 :dupengwei - 原文 :http://developer.android.com/training/tv/tif/index.html 


看 电视 直播 节目 和 其 他 连续 的 、 基 于 频道 的 内 容 是 TV 体验 的 主要 部 分 。Android 通过 Android 
5.0 中 的 TV Input Framework 支 持 直播 视频 内 容 的 接收 和 重 放 (API Level 21) 。 该 框架 提供 
了 一 个 统一 的 方法 ， 从 硬件 源 (如 HDMI 端 口 和 内 置 调谐 器 ) 和 软件 源 (如 流传 在 互联 网 上 的 
视频 ) 接收 音频 和 视频 内 容 。 


该 框架 能 使 开发 人 员 通 过 实现 TV 输入 服务 定义 直播 TV 输入 源 。 该 服务 发 布 一 个 频道 和 节目 列 
表 到 一 个 TV Provider 上 。 电视 设 备 的 直播 电视 应 用 从 TV Provider 获 取 可 用 的 频道 和 节目 列表 
并 显示 给 用 户 。 当 用 户 选择 某 个 特定 的 频道 ， 直 播 TV 应 用 软件 通过 TV Input Manager 为 相关 
TV 输入 服务 创建 一 个 会 话 ， 并 告诉 TV 输入 服务 调整 到 请 求 频 道 ， 然 后 将 内 容 显 示 到 TV 应 用 软 
件 提供 的 显示 器 上 。 
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图 1. 电 视 输 入 框架 功能 图 


TV Input Framework 的 设计 目的 是 提供 各 种 各 样 的 TV 输入 源 并 把 它们 整合 到 一 个 单一 的 用 户 
界面 供用 户 浏览 、 查 看 和 享受 内 容 。 为 你 想 要 传播 的 节目 构建 一 个 TV 输入 服务 之 后 ， 用 户 可 
以 更 加 轻易 地 通过 TV 设备 收看 这 些 节目 。 


更 多 关于 TV 输入 框架 的 信息 ， 请 参考 android.media.tv » 


ROA 
U IT 


TV 应 用 清单 


编写 :awong1900 - 原 
文 :http://developer.android.com/training/tv/publishing/checklist.html 


用 户 喜 欢 的 TV 应 用 应 是 体验 一 致 的 ， 有 遇 辑 的 和 可 预测 的 。 他 们 可 以 在 应 用 内 四 处 浏览 ， 并 
且 不 会 a mt Me MA UA es 有 色彩 的 和 起 作用 的 界面 ， 
这 样 的 体验 会 很 好 。 把 这 些 想法 放 在 脑子 中 ， 我 们 能 适合 Android TV 的 应 用 并 达到 用 户 
的 期 望 


这 个 清单 禾 盖 了 应 用 和 游戏 的 开发 的 主要 方面 去 确保 我 们 的 应 用 提供 了 最 好 的 体验 。 额 外 的 
游戏 注意 事项 仅 被 包含 在 游戏 小 节 。 


X T Google Play 中 Android TV 应 用 的 质量 标准 ， 参 考 TV App Quality ° 


TV 格式 因素 的 支持 


这 些 清 单项 目 使 用 在 游戏 和 应 用 中 。 


1. 确定 manifest 的 主 activity 使 用 cATEGORY_LEANBACK_LAUNCHER 。 查看 Declare a TV 
Activity ° 
2. 提供 每 种 语言 的 主屏 幕 横幅 支持 。 
启动 应 用 横幅 大 小 为 320x180 px 

o 横幅 资源 放 在 drawables/xhdpi 目录 

o 横幅 图 像 包 含 本 地 化 的 文本 去 识别 应 用 。 查看 Provide a home screen banner ° 
3. 消除 不 支持 的 硬件 要 求 。 查看 Declaring hardware requirements for TV ° 
4. 确保 没有 隐 式 的 权限 需求 。 查看 Declaring permissions that imply hardware features ° 


A P AGE 


这 些 清 单项 使 用 在 游戏 和 应 用 中 。 


.提供 适合 横 屏 模式 的 布局 资源 。 BA Build Basic TV Layouts ° 

.确保 文本 和 控件 在 一 定 距离 外 看 是 足够 大 的 。 查看 Build Useable Text and Controls ° 

. 为 HDTV 屏幕 提供 高 分 辩 率 的 位 图 和 图 标 。 查看 Manage Layout Resources for TV » 

.确保 我 们 的 图 标 和 logo 符 合 Android TV 的 规范 。 查看 Manage Layout Resources for 
TV 

5. 允许 布局 使 用 overscan。 查看 Overscan 。 

6. 使 每 一 个 布局 元 素 都 能 用 D-pad 和 游戏 控制 器 操作 。 查看 Creating Navigation 和 


AUO N> 


10. 


Handling Controllers ° 

当 用 户 通过 文本 搜索 时 改变 背景 图 像 。 查看 Update the Background ° 

在 Leanback fragments 中 定制 背景 颜色 去 匹配 品牌 。 查 看 Customize the Card View ° 
确保 我 们 的 UI 不 需要 触摸 屏 。 查看 Touch screen and Declare touch screen not 
required。 

遵循 有 效 的 广告 的 指导 。 查看 Provide Effective Advertising 。 


搜索 和 发 现 内 容 


1. 
2. 


清单 项 使 用 在 游戏 和 应 用 中 。 


在 Android TV 全 局 搜索 框 中 提供 搜索 结果 。 查看 Provide Data 。 
提供 TV 特定 数据 字段 的 搜索 。 查看 ldentify Columns e 


3. 确保 应 用 的 详情 屏幕 有 可 发 现 的 内 容 以 便 用 户 立 即 开始 观看 。 查 看 Display Your App in 


the Details Screen。 
放置 相关 的 ， 可 操作 的 内 容 和 目录 在 主屏 幕 ， 使 用 户 容 易 的 发 现 内 容 。 查 
Recommending TV Content ° 


游戏 


1. 


清单 项 目 使 用 在 游戏 。 


在 manifest 中 用 iscame 标记 让 游戏 显示 在 主屏 幕 上 。 查看 Show your game on the 
home screen。 

确保 游戏 控制 器 可 以 不 依靠 开始 ， 选 择 ， 或 者 菜单 键 操作 (不 是 所 有 控制 器 有 这 些 按键 ) 。 
查看 Input Devices。 

使 用 通常 的 游戏 手柄 布局 〈 不 包括 特殊 的 控制 器 品牌 ) 去 显示 游戏 按键 示意 图 。 查 

看 Show controller instructions ° 

检查 网 络 和 WiFi 连 接 。 3 Networking ° 

提供 给 用 户 清晰 的 退出 提示 。 查看 Exit 。 


创建 企业 级 应 用 


编写 :craftsmanBai - http://z1ng.net - 原 
x-:http://developer.android.com/training/enterprise/index.html 
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G> B B 


Android 框 架 提供 安全 支持 、 数 据 分 离 、 企 业 环 境 管理 的 功能 。 作 为 应 用 开发 者 ， 通 过 适当 地 
处 理 企 业 安全 和 功能 限制 ， 你 可 以 让 你 的 应 用 程序 吸引 更 多 的 企业 客户 。 也 可 以 修改 你 的 应 
用 使 技术 管理 员 可 远程 配置 使 用 企业 资源 。 


为 了 帮助 企业 将 安 草 设备 和 应 pii 入 工作 场所 ，Google 通 过 Android for Work 为 设备 的 分 
配 和 管理 提供 了 一 套 API 和 服务 。 这 项 计划 ， 企 业 可 以 连接 到 企业 移动 性 管理 (EMM) 
供应 商 ， 将 Android 整 合 到 ju o 


通过 下 面 的 链接 获取 ， 可 以 了 解 更 多 关于 如 何 更 新 您 的 Android 应 用 程序 来 支持 企业 环境 或 建 
立 企业 解决 方案 的 信息 。 


企业 级 应 用 开发 


Android 企 业 级 应 用 


了 解 在 企业 环境 中 如 何 使 您 的 应 用 程序 运行 顺畅 ， 限 制 设 备 的 功能 和 数据 访问 。 通 过 加 入 限 


制 进一步 支持 企业 使 用 你 的 app， 让 管理 员 可 以 远程 配置 使 用 你 的 应 用 程序 : 
确保 与 管理 兼容 : 
http://developer.android.com/training/enterprise/app-compatibility.html 

加 入 应 用 限制 : 
http://developer.android.com/training/enterprise/app-restrictions.html 

应 用 限制 计划 : 
http://developer.android.com/samples/AppRestrictionSchema/index.html 

应 用 限制 执行 者 : 


http://developer.android.com/samples/AppRestrictionEnforcer/index.html 


设备 与 应 用 管理 


学 习 如 何 为 应 用 程序 建立 策略 控制 器 ， 使 企业 的 技术 管理 人 员 来 管理 设备 ， 管 理 企业 应 用 程 


序 ， 并 提供 访问 公司 资源 的 权限 : 

建立 工作 策略 控制 : 
http://developer.android.com/training/enterprise/work-policy-ctrl.html 
基本 管理 模型 : 


http://developer.android.com/samples/BasicManagedProfile/index.html 
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利用 Managed Profile 确保 兼容 性 


编写 : zenlynn 原文 : http://developer.android.com/training/enterprise/app- 
compatibility.html 


Android 平台 允许 设备 有 managed pole e managed profile 由 管理 员 控制 ， 它 的 功能 和 用 户 
原本 的 profile 的 功能 是 分 别 设置 的 。 通 过 这 种 方法 ， 在 用 户 设 备 上 和 运行 的 企业 所 定制 应 用 程 
序 和 数据 的 环境 就 在 企业 的 控制 之 下 ， 同 时 用 户 还 能 使 用 私人 的 应 用 程序 和 profile 。 


本 节 课 展示 了 如 何 修 改 你 的 应 用 程序 ， 使 之 能 够 在 有 managed profile 的 设备 上 可 靠 运行 。 除 
了 一 般 应 用 开发 的 最 佳 实 践 外 ， 你 不 用 做 任何 事 。 然 而 ， 在 有 managed profile 的 设备 上 ， 最 
佳 实践 的 其 中 一 些 规范 变 得 尤为 重要 。 本 文件 强调 了 你 所 需要 了 解 的 问题 。 


概述 


用 户 经 常 想 在 企业 环境 中 使 用 他 们 的 私人 设备 。 这 种 情况 可 能 让 企业 陷入 困境 。 如 果 用 户 使 
用 他 们 的 私人 设备 ， 企 业 不 得 不 担心 在 这 个 不 受 控制 的 设备 上 的 机 密 信 息 (例如 员工 的 电子 
邮件 和 通讯 录 ) 。 


为 了 处 理 这 种 情况 ，Android 5.0 (API 21) 允许 企业 设置 managed profile。 如 果 设备 有 
managed profile， 这 个 profile 的 设置 是 在 企业 管理 员 的 控制 之 下 的 。 管 理 员 可 以 选择 在 这 
profile 之 下 ， 什 么 应 用 程序 可 以 运行 ， 什 么 设备 功能 可 以 允许 。 


如 果 一 个 设备 有 managed profile， 那 么 ， 无 论 应 用 程序 在 哪个 profile 之 下 运行 ， 都 意味 着 : 


e. 默认 情况 下 ， 大 部 分 的 intent 无 法 从 一 个 profile 跨越 到 另 一 个 。 如 果 在 某 个 profile 之 下 
的 一 个 应 用 程序 创建 了 intent， 而 这 个 无 法 响应 ， 又 因为 profile 的 限制 这 个 
intent 不 允许 跨越 到 其 他 profile， 那 么 ， 这 个 请 求 就 失败 了 ， 应 用 程序 可 能 意外 关闭 。 


e profile 管理 员 可 以 在 managed profile 中 限制 哪个 系统 应 用 程序 可 以 运行 。 这 个 限制 可 能 
导致 在 managed profile 中 一 些 常见 的 intent 无 法 处 理 。 


e 因为 managed profile 和 非 managed profile 有 各 自 的 存储 区 域 ， 导致 文件 URI 在 一 个 
profile 中 有 效 ， 但 在 其 他 profile 中 无 效 。 在 一 个 profile 中 创建 的 intent 可 能 在 其 他 
profile (取决 于 profile 设置 ) 中 被 响应 ， 所 以 在 intent 中 放置 文件 URI 是 不 安全 的 。 


防止 失败 的 intent 


在 一 个 有 managed profile 的 设备 上 ，intent 是 否 能 从 一 个 profile 跨越 到 另 一 个 ， 存 在 着 限 
制 。 大 多 情况 下 ， 一 个 intent 在 哪个 profile 中 创建 ， profile 中 响应 。 如 果 那 个 
profile 中 无 法 响应 ， 就 算 在 其 他 profile 中 可 以 响应 ， 这 个 intent 也 不 会 被 响应 ， 而 且 创建 这 
个 intent 的 应 用 程序 会 意外 关闭 。 


profile 管理 员 可 以 选择 哪个 intent 可 以 从 一 个 profile 跨越 到 另 一 个 。 因 为 是 由 管理 员 做 决 
定 ， 所 以 你 无 法 预先 知道 哪个 intent 可 以 跨越 边界 。 管 理 员 设置 了 这 个 策略 ， 而 且 可 以 在 任 
何 时候 自 由 更 改 。 


在 你 的 应 用 程序 启动 一 个 activity 之 前 ， 你 应 该 验证 这 是 可 行 的 。 你 可 以 调用 
Intent.resolveActivity() 方法 来 验证 。 如 果 无 法 处 理 ， 方 法 会 返回 null。 如 果 方 法 返回 值 非 
空 ， 那 么 至 少 有 一 个 方法 可 以 处 理 这 个 intent， 所 以 创建 这 个 intent 是 安全 的 。 这 种 情况 下 ， 
或 者 是 因为 在 当前 profile 中 可 以 响应 ， 或 者 是 因为 intent 被 允许 跨越 到 可 以 处 理 的 其 他 
profile 中 ，intent 可 以 被 处 理 。 (更 多 关于 响应 intent 的 信息 ， 请 查看 Common Intents » ) 


例如 ， 如 果 你 的 应 用 程序 需要 设置 定时 器 ， 就 需要 检查 是 否 能 响应 ACTION SET TIMER 
intent。 如 果 应 用 程序 无 法 响应 这 个 intent， Us 当 的 行动 (例如 显示 一 个 错误 信 
息 ) © 


public void startTimer(String message, int seconds) { 


NE SA KENE Seteerme ntenk 

Intent timerIntent = new Intent(AlarmClock.ACTION_SET_TIMER) 
.putExtra(AlarmClock.EXTRA MESSAGE, message) 
.putExtra(AlarmClock.EXTRA LENGTH, seconds) 
.putExtra(AlarmClock.EXTRA SKIP UI, true); 


// Check if there's a handler for the intent 
if (timerIntent.resolveActivity(getPackageManager()) == null) ( 


// Can't resolve the intent! Fail this operation cleanly 
// (perhaps by showing an error message) 


} else { 


// Intent resolves, it's safe to fire it off 
startActivity(timerIntent); 


跨越 profile 共享 文件 


有 时 候 应 NA 问 自 己 的 o 例如， 一 个 图 片 库 应 用 可 能 想 与 图 
片 编辑 器 共享 它 的 图 片 。 一 般 共 享 文件 有 两 种 方法 : 通过 文件 URI 或 者 内 容 URI 。 


一 个 文件 URI 是 由 前 级 file: 和 文件 在 设备 中 存储 的 绝对 路 径 组 成 的 。 然 而 ， 因 为 
managed profile 和 私人 profile 有 各 自 的 存储 区 域 ， 所 以 一 个 文件 URI 在 一 个 profile 中 是 有 
效 的 ， 在 其 他 profile 中 是 无 效 的 。 这 种 情况 意味 着 ， 如 果 你 要 在 intent 中 放置 一 个 文件 
URI > RZA intent 要 在 其 他 profile 中 响应 ， 那 么 响应 方 是 不 能 访问 这 个 文件 的 。 


你 应 该 取而代之 用 内 容 URI 共享 文件 。 内 容 URI 用 一 种 更 安全 、 更 易于 分 享 的 方式 来 识别 
件 。 内 容 URI 包括 了 文件 路 径 ， 文 件 提供 者 ， 以 及 文件 ID。 你 可 以 通过 FileProvider bend 
文件 生成 内 容 ID。 然 后 ， 你 就 可 以 和 (甚至 在 其 他 profile 中 的 ) 其 他 应 用 程序 共享 内 容 ID 。 
响应 方 可 以 使 用 内 容 ID 来 访问 实际 文件 。 


例如 ， 这 里 展示 了 你 怎么 获得 一 个 指定 文件 URI YAS URI: 


// Open File object from its file URI 


File fileToShare = new File(fileUriToShare); 


Uri contentUriToShare - FileProvider.getUriForFile(getContext(), 
"com.example.myapp.fileprovider", fileToShare); 


当 你 调用 getUriForFile() 方法 时 ， 必 须 包 括 文件 提供 者 的 权限 (在 这 个 例子 里 是 
"com.example.myapp.fileprovider" ) ， 在 应 用 程序 的 manifest 中 ， i \ 元 素 设 受 定 这 个 权限 。 
更 多 关于 用 内 容 URI 共享 文件 的 信息 ， 请 查看 共享 文件 。 


在 managed profile 环境 测试 你 的 应 用 程序 的 兼容 
性 


你 要 在 有 managed profile 的 环境 中 测试 你 的 应 用 程序 ， 以 发 现 会 引起 运行 失败 的 问题 。 在 一 
个 有 managed profile 的 设备 中 测试 是 一 个 验证 你 的 应 用 程序 正确 响应 intent 的 好 办 法 : 无 法 
响应 的 时 候 不 创建 intent， 不 使 用 无 法 跨越 profile 的 URI 等 等 。 


我 们 提供 了 一 个 示例 应 用 程序 ，BasicManagedProfile， 你 可 以 用 它 在 一 个 运行 Android 5.0 
或 者 更 高 系统 的 Android 设备 上 设置 一 个 managed profile。 这 个 应 用 程序 为 在 有 managed 
profile 的 环境 中 来 测试 你 的 应 用 程序 提供 了 一 个 简单 的 方法 。 你 也 可 以 按照 下 面 的 方法 用 这 
个 应 用 程序 来 设置 你 的 managed profile : 


。 在 managed profile 中 设 定 哪些 默认 应 用 程序 可 以 使 用 
e 设 定 哪些 intent 被 允许 从 一 个 profile 跨越 到 另 一 个 


如 果 你 通过 USB 线 手 动 安装 一 个 有 managed profile 的 应 用 程序 ， 那 么 在 managed profile 
和 非 managed profile 之 中 都 安装 有 这 个 应 用 程序 。 只 要 你 安装 了 应 用 程序 ， 你 就 能 在 以 下 条 
件 下 进行 测试 : 


e 如 果 一 个 intent 可 以 被 一 个 默认 的 应 用 程序 (例如 相机 应 用 程序 ) 响应 ， 试 试 managed 


profile 中 禁用 这 个 默认 应 用 程序 ， 然 后 验证 这 个 应 用 程序 可 以 做 出 恰当 的 行为 。 


e 如 果 你 创建 了 一 个 intent 希望 被 其 他 应 用 程序 响应 ， 试 试 启用 以 及 禁用 这 个 intent 从 一 
个 profile 跨越 到 另 一 个 的 权限 。 验 证 在 这 两 种 情况 下 应 用 程序 都 能 做 出 恰当 的 行为 。 如 
R intent 不 允许 在 profile Z HAR > A $ AT profile 是 否 能 做 出 响应 ， 都 要 验证 应 用 程 
序 能 做 出 恰当 的 行为 。 例 如 ， 如 果 你 的 应 用 程序 创建 了 一 个 地 图 相关 的 intent， 试 试 以 下 
每 一 种 情况 : 

o 设备 允许 地 图 intent 从 一 个 profile 跨越 到 另 一 个 ， 并 且 在 另 一 个 《并 非 应 用 程序 所 
运行 的 ) profile 之 中 有 恰当 的 响应 

o 设备 不 允许 地 图 intent 在 profile 之 间 跨 越 ， 但 是 在 应 该 程序 所 运行 的 profile 之 中 有 
恰当 的 响应 

o 设备 不 允许 地 图 intent 在 profile 之 问 跨越 ， 并 且 在 设备 的 profile 之 中 没有 恰当 的 响 
AL 


e 如 果 你 在 intent 里 放置 了 内 容 ， 不 管 是 在 当前 profile 之 中 ， 还 是 在 跨越 profile 之 后 ， 都 
要 验证 intent 能 有 恰当 的 行为 。 


在 managed profile 环境 测试 : 提示 与 技巧 
你 会 发 现在 有 managed profile 的 设备 里 进行 测试 有 一 些 技巧 。 


e 如 前 所 述 ， 当 你 侧 载 一 个 应 用 程序 到 一 个 有 managed profile 的 设备 里 ， 是 在 managed 
profile 和 非 managed profile 之 中 都 安装 了 。 如 果 你 愿意 ， 你 可 以 从 一 个 profile 之 中 出 
除 ， 在 另 一 个 profile Z t & T» 


e 在 安 卓 调试 桥 (adb) shell 端 可 用 的 activity manager 命令 大 部 分 都 支持 --user 标 
识 ， 你 可 以 用 之 设 定 运 行 应 用 程序 的 用 户 。 通 过 设 定 一 个 用 户 ， 你 可 以 选择 是 在 
managed profile 之 中 运行 ， 还 是 在 非 managed profile 之 中 运行 。 更 多 信息 ， 请 查看 
ADB Shell Commands ° 


e 为 了 找到 设备 上 的 活跃 用 户 ， 使 用 adb 包 管 理 器 的 list users 命令 。 输 出 的 字符 串 中 
第 一 个 数字 是 用 户 ID， 你 可 以 用 于 --user 标识 。 更 多 信息 ， 请 查看 ADB Shell 
Commands ° 


例如 ， 为 了 找到 一 个 设备 上 的 用 户 ， 你 会 运行 这 个 命令 : 
$ adb shell pm list users 


UserInfo(0:Drew:13) running 
UserInfo{10:work profile:30} running 


在 这 里 ， 非 managed profile ("Drew") 有 个 ID 为 0 的 用 户 ， 而 managed profile 有 个 ID 为 
10 的 用 户 。 要 在 工作 profile 之 中 运行 一 个 应 用 程序 ， 你 会 用 到 这 样 的 命令 : 


$ adb shell am start --user 10 \ 
-n "com.example.myapp/com.example.myapp.testactivity" \ 
-a android.intent.action.MAIN -c android.intent.category.LAUNCHER 


实现 app 的 限制 


编写 : zenlynn 原文 : http://developer.android.com/training/enterprise/app- 


restrictions.html 


如 果 你 为 企业 市 场 开发 ， 你 可 能 需要 满足 企业 政策 的 特殊 要 求 。 应 用 程序 的 限制 允许 企 


业 管 理 员 远程 设 定 app 。 这 种 能 力 对 于 部 署 了 managed profile 的 企业 app Kit > HHA 
用 。 


例如 ， 一 个 企业 可 能 需要 核准 的 app 允许 企业 管理 员 : 
© 为 一 个 网 页 浏览 器 添加 白 名 单 或 黑 名 单 网 址 
e 配置 是 否 允 许 一 个 app 通过 蜂窝 网 络 同步 内 容 ， 或 只 能 通过 Wi-Fi 
。 配置 app 的 电子 邮件 设 定 
这 个 指南 展示 了 如 何在 你 的 app 实现 这 个 配置 设 定 。 


注意 : 由 于 历史 原因 ， 这 些 配置 设 定 被 称 为 限制 ， 并 在 文件 与 类 中 使 用 这 个 术语 (例如 
RestrictionsManager) 。 然 而 ， 这 些 限制 实际 上 可 以 实现 各 种 各 样 的 配置 选项 ， 并 不 只 
是 限制 app 的 功能 。 


远程 配置 概述 


app 定义 了 管理 员 可 以 远程 设 定 的 限制 和 配置 选项 。 限 制 提 供 者 可 以 随意 改变 配置 设 定 。 如 
果 你 的 app 运 2a) managed profile 中 ， 企 业 管理 员 可 以 改变 该 app 的 限制 。 


限制 提供 者 是 运行 在 同一 个 设备 上 的 另 一 个 app ° 个 app 通常 是 由 企业 管理 员 控 制 。 企 业 
管理 员 向 限制 提供 者 app 传达 限制 的 改变 。 这 个 app beds 地 改变 你 的 app 的 限制 。 


提供 外 部 可 配置 的 限制 : 


e 在 你 app 的 manifest 中 声明 限制 。 这 么 做 允许 企业 管理 员 通 过 Goodle Play 的 接口 读 取 
app 的 限制 。 


每 当 app 恢复 ， 使 用 RestrictionsManager 对 象 检 查 当 前 限制 ， 并 改变 你 的 app 的 UI fe 
行为 以 符合 这 些 限 制 。 


e 监听 ACTION APPLICATION RESTRICTIONS CHANGED intent。 当 你 收 到 这 个 广播 


时 ， 检 查 RestrictionsManager 看 看 当前 限制 是 什么 ， 并 对 你 的 app 的 行为 做 出 任何 必 
要 的 改变 。 


定义 app 的 限制 


你 的 app 支持 任何 你 想 要 定义 的 限制 。 你 在 限制 文件 中 声明 app 的 限制 ， 在 manifest 中 声明 
限制 文件 。 创 建 一 个 限制 文件 允许 其 他 app 检查 你 的 app 提供 的 限制 。 企 业 移动 管理 
(EMM) 合作 者 可 以 通过 Google Play 接口 来 读 取 你 的 app 的 限制 。 


为 了 定义 你 的 app 的 远程 配置 选项 ， 把 以 下 元 素 放 在 你 的 manifest 中 的 \ 元 素 里 。 


«meta-data android:name="android.content.APP_RESTRICTIONS" 


android: resource="@xml/app_restrictions" /> 


在 res/xml 文件 夹 中 创建 一 个 名 为 app_restrictions.xml 的 文件 。 该 文件 的 结构 在 
eens Manager 参考 文献 中 有 所 描述 。 该 文件 有 一 个 单独 的 顶 an <restrictions> 
元 素 ， 这 个 元 素 包 括 一 个 «restrictions 子 元 素 对 应 app 的 每 一 个 配置 选项 。 


注意 : 不 要 创建 限制 文件 的 地 区 化 版 本 。 你 的 app 只 允许 有 一 个 限制 文件 ， 这 样 你 的 
app 在 所 有 地 区 的 限制 才 会 保持 一 致 。 
在 一 个 企业 环境 中 ，EMM 一 般 会 使 用 该 限制 的 框架 为 IT 管理 员 生 成 远程 控制 台 ， 所 以 管理 
员 可 以 远程 配置 你 的 app。 


例如 ， 假 设 你 的 app 可 以 被 远程 配置 允许 或 禁止 它 在 蜂 帘 连接 下 下 载 数据 。 你 的 app 就 会 有 
一 个 像 这 样 的 «restriction» 元 素 : 


«?xml version="1.0" encoding="utf-8"?> 
«restrictions xmlns:android="http://schemas.android.com/apk/res/android" > 


«restriction 
android:key-z"download on cell" 
android:title-"Qstring/download on cell title" 
android:restrictionType-"bool" 
android:description-"Qstring/download on cell description" 
android:defaultValue-"true" /» 


«/restrictions» 


RestrictionsManager 的 参考 文献 中 记载 了 android:restrictionrype 元 素 所 支持 的 类 型 。 
注意 : Goole Play for Work 不 支持 bundle 和 bundle array 限制 类 型 。 


使 用 每 个 限制 的 android:key 属性 从 限制 bundle 中 读 取 它 的 值 。 为 此 ， 每 个 限制 必须 有 一 
个 独特 的 key 字符 串 ， 并 且 不 能 被 地 区 化 。 它 必须 用 一 个 sting 直接 量 指明 。 


注意 : 如 在 资源 地 区 化 所 说 ， 在 一 个 产品 app 中 ， android:title 和 
android:description 应 该 从 地 区 化 资源 文件 中 提取 出 来 。 


限制 提供 者 可 以 询问 app 来 找到 该 app 可 用 限制 的 细节 ， 包 括 它 们 的 描述 文本 。 限 制 提 供 者 
和 企业 管理 员 可 以 在 任何 时 候 ， 甚 至 app 没有 在 运行 的 时 候 ， 改 变 它 的 限制 。 


检查 app 的 限制 


当 其 他 app 改变 你 的 app 的 限制 设 定时 ， 你 的 app 不 会 被 自动 通知 。 反 而 需要 你 在 app 启动 
或 恢复 的 时 候 检 查 有 哪些 限制 ， 并 且 监 听 系 统 intent 来 发 现 当 你 的 app 运行 的 时 候 限制 是 否 
发 生 改 变 。 


为 了 知道 当前 限制 设 定 ， 你 的 app 使 用 一 个 RestrictionsManager 对 象 。 你 的 app 应 该 在 以 
下 时 候 检 查 当 前 限制 : 


e X app 启动 或 者 恢复 的 时 候 ， 在 它 的 onResume() 方法 里 检查 
e 如 监听 app 配置 的 改变 中 所 说 ， 当 app 被 提示 限制 改变 的 时 候 


为 了 获得 一 个 RestrictionsManager 对 象 ， 使 用 getActivity() 取得 当前 activity， 然 后 调用 
activity 的 Activity.getSystemService() 方法 : 


RestrictionsManager myRestrictionsMgr = 
(RestrictionsManager) getActivity() 
.getSystemService(Context.RESTRICTIONS SERVICE); 


一 旦 你 有 了 RestrictionsManager， 你 可 以 通过 调用 它 的 getApplicationRestrictions() 方法 取 
得 当前 的 限制 设 定 : 


Bundle appRestrictions = myRestrictionsMgr.getApplicationRestrictions(); 


: 方便 起 见 ， 你 也 可 以 用 UserManager 取得 当前 限制 ， 调 用 
Ri ERE 即 可 。 这 个 方法 与 
RestrictionsManager.getApplicationRestrictions() 起 到 完全 相同 的 作用 。 


getApplicationRestrictions() 方法 需要 从 数据 存储 区 获得 数据 ， 所 以 要 尽量 少 用 。 不 要 每 次 你 
需要 知道 当前 限制 的 时 候 就 调用 这 个 方法 。 你 应 该 只 在 你 的 app 启动 或 恢复 的 时 候 调用 ， 并 
且 缓 存 所 取得 的 限制 bundle。 然 后 ， 如 监听 app 配置 的 改变 中 所 说 ， 在 你 的 app 活动 的 时 
候 ， 监 听 ACTION APPLICATION RESTRICTIONS CHANGED intent 来 发 现 限制 是 否 改 
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3 4% 89 app 使 用 RestrictionsManager.getApplicationRestrictions() 检查 限制 时 ， 我 们 建议 你 
检查 企业 管理 员 是 否 把 键 值 对 KEY RESTRICTIONS PENDING 设置 为 true。 如 果 设 置 了 ， 
你 应 该 阻止 用 户 使 用 这 个 app， 并 提示 他 们 联系 他 们 的 企业 管理 员 。 然 后 ， 这 个 app 应 该 继 
续 正常 运行 ， 注 册 ACTION. APPLICATION. RESTRICTIONS CHANGED pn 


Implementing App Restrictions 


getApplicationRestrictions() 
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Figure 1. 在 注册 广播 之 前 检查 限制 是 否 暂 挂 


读 取 并 应 用 限制 


getApplicationRestrictions() 方法 返回 一 个 Bundle， 其 中 包含 了 被 设置 的 每 个 限制 的 键 值 对 。 
这 些 值 的 类 型 是 Boolean , int, String , String[] , Bundle , Bundle[] ° 只 要 你 有 了 限制 
Bundle ， 你 就 可 以 用 标准 的 Bundle 方法 针对 数据 类 型 来 检查 当前 的 限制 设置 ， 比 如 
getBoolean() 或 者 getString()。 


注意 : 限制 Bundle 为 每 个 被 限制 提供 者 显 式 设置 的 限制 都 ni 一 个 条 目 。 但 是 ， 你 不 
能 只 因为 你 在 限制 XML 文件 中 定义 了 一 个 默认 值 ， 就 假定 这 个 限制 就 会 在 bundle 里 出 
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你 基于 当前 的 限制 设 定 ， 为 你 的 app 采取 合适 的 行动 。 比 如 ， 如 果 你 的 app 有 一 个 限制 架构 
来 指明 是 否 它 能 在 蜂窝 连接 (就 像 在 定义 app 的 限制 的 例子 里 一 样 ) 中 下 载 ， 而 你 发 现 限制 
设置 为 false， 那 么 你 不 得 不 禁止 数据 下 载 ， 除 非 设 备 在 Wi-Fi 连接 下 ， 正 如 下 面 的 实例 代码 
所 展示 的 : 


mplementing App Restrictions 


boolean appCanUseCellular; 
if appRestrictions.containsKey("downloadOnCellular") { 

appCanUseCellular = appRestrictions.getBoolean("downloadOnCellular"); 
i else {f 

// here, cellularDefault is a boolean set with the restriction's 


// default value 
appCanUseCellular = cellularDefault; 


if (!appCanUseCellular) { 
// ...turn off app's cellular-download functionality 
// ...show appropriate notices to user 


注意 : 该 限制 架构 必须 向 前 向 后 兼容 ， 因 为 Google Play for Work 对 于 每 个 app 只 给 予 
EMM 一 个 版 本 的 限制 架构 。 


大 ZR 
监听 app 限制 的 改变 
每 当 app 的 限制 被 改变 ， 系 统 就 创建 ACTION. APPLICATION. RESTRICTIONS CHANGED 
intent。 你 的 app 必须 监听 这 个 intent， 这 样 你 就 能 在 限制 设 定 改 变 的 时 候 改 变 app 的 行为 。 


注意 : ACTION APPLICATION RESTRICTIONS CHANGED intent 只 发 送 给 动态 注册 
的 监听 者 ， 而 不 发 送 给 在 app manifest 里 声明 的 监听 者 。 


以 下 代码 展示 了 如 何 为 这 个 intent 动态 注册 一 个 广播 接收 者 : 


IntentFilter restrictionsFilter = 
new IntentFilter(Intent.ACTION APPLICATION RESTRICTIONS CHANGED); 


BroadcastReceiver restrictionsReceiver = new BroadcastReceiver() { 
@Override public void onReceive(Context context, Intent intent) { 


// Get the current restrictions bundle 
Bundle appRestrictions - 


myRestrictionsMgr.getApplicationRestrictions(); 


// Check current restrictions settings, change your app's UI and 
// functionality as necessary. 


ur 


registerReceiver(restrictionsReceiver, restrictionsFilter); 


Implementing App Restrictions 


注意 : 一 般 来 说 ， 当 你 的 app 中 止 时 不 需要 被 通知 限制 的 改变 。 相 反 ， 这 个 时 候 你 需要 
注销 你 的 广播 接收 者 。 当 app 恢复 时 ， 你 首先 要 检查 当前 的 限制 (正如 在 检查 app 的 限 
制 中 所 讨论 的 ) ， 然 后 注册 你 的 广播 接收 者 ， 以 保证 在 app 活动 期 间 如 果 有 限制 改变 你 
会 被 通知 。 
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创建 设备 策略 控制 器 


编写 : zenlynn 原文 : http://developer.android.com/training/enterprise/work-policy- 
ctrl.html 


在 Android for Work 的 部 署 中 ， 企 业 需 要 保持 对 员工 设备 的 某 些 方面 的 控制 。 企 业 需 要 确保 
工作 相关 的 信息 被 加 密 ， 并 与 员工 的 私人 数据 分 离 。 企 业 也 可 能 需要 限制 设备 的 功能 ， 例 如 
设备 是 否 被 允许 使 用 相机 。 而 且 企业 也 可 能 需要 那些 被 批准 的 应 用 提供 应 用 限制 ， 所 以 企业 
可 以 根据 需要 关闭 或 打开 应 用 的 功能 。 


为 了 处 理 这 些 任 务 ， 企 业 开发 并 部 署 设 备 策略 控制 器 应 用 (以 前 称 为 工作 策略 控制 器 ) 。 该 
应 用 被 安装 在 每 一 个 员工 的 设备 中 。 安 装 在 每 一 个 员工 设备 中 的 控制 应 用 创建 了 一 个 企业 用 
PÈ profile， 它 可 以 区 别 用 户 的 私人 账户 以 访问 企业 应 用 和 数据 。 该 控制 应 用 同时 也 是 企业 管 
理 软件 和 设备 之 间 的 桥梁 ; 当 企业 需要 改变 配置 的 时 候 就 告诉 控制 应 用 ， 然 后 控制 应 用 适当 
地 为 设备 和 其 他 应 用 改变 设置 。 


该 课程 描述 了 如 何在 Android for Work 的 部 署 中 为 设备 开发 一 个 设备 策略 控制 器 。 该 课程 描 
述 了 如 何 创建 一 个 企业 用 户 profile， 如 何 设置 设备 策略 ， 以 及 如 何在 managed profile 中 为 其 
他 运行 中 的 应 用 进行 限制 。 


主意 : 该 课程 的 内 容 并 不 包括 在 企业 控制 之 下 ， 设 备 中 唯一 的 profile 就 是 managed 
pons 的 情况 。 


设备 管理 概述 


在 Android for Work 的 部 署 中 ， 企 业 管理 员 可 以 设置 策略 来 控制 员工 设备 和 应 用 的 行为 。 企 
业 管 理 员 用 企业 移动 管理 (EMM) 供应 商 提供 的 软件 设置 这 些 策略 。EMM 软件 与 每 一 个 设 
备 上 的 设备 策略 控制 器 进行 通讯 。 设 备 策略 控制 器 相应 地 对 每 一 个 私人 设备 上 企业 用 户 


profile 的 设置 和 行为 进行 管理 。 


设备 政策 管理 器 内 置 于 设备 管理 应 用 现 有 的 模式 中 ， 如 设备 管理 中 所 说 。 特 别 是 ， 你 的 
应 用 需要 创建 DeviceAdminReceiver 的 子 类 ， 如 上 述 文 件 所 说 。 


Managed profiles 


用 户 经 常 想 在 企业 环境 中 使 用 他 们 的 私人 设备 。 这 种 情况 可 能 让 企业 陷入 困境 。 如 果 用 户 使 
用 他 们 的 私人 设备 ， 企 业 不 得 不 担心 在 这 个 不 受 控制 的 设备 上 的 机 密 信 息 (例如 员工 的 电子 
邮件 和 通讯 录 ) 。 


为 了 处 理 这 种 情况 ，Android 5.0 (API 21) 允许 企业 使 用 managed profile 建立 一 个 特别 的 企 
业 用 户 profile， 或 是 在 Android for Work 计划 中 建立 一 个 企业 profile。 如 果 设 备 有 企业 
managed profile， 该 profile 的 设置 是 在 企业 管理 员 的 控制 之 下 的 。 管 理 员 可 以 选择 在 这 个 
profile 之 下 ， 什 么 应 用 程序 可 以 运行 ， 什 么 设备 功能 可 以 允许 。 


创建 Managed Profile 


要 在 一 个 已 经 有 了 私人 profile 的 设备 上 创建 一 个 managed profile， 首 先 得 看 看 该 设备 是 否 支 
持 FEATURE MANAGED USERS 系统 特性 ， 才 能 确定 该 设备 是 否 支持 managed profile : 


PackageManager pm = getPackageManager(); 
if (!pm.hasSystemFeature(PackageManager.FEATURE MANAGED USERS)) { 


// This device does not support native managed profiles! 


如 果 该 设备 支持 managed profile， 通 过 发 送 一 个 带 有 
ACTION_PROVISION_MANAGED_PROFILE 行动 的 intent 来 创建 一 个 managed profile 。 
另外 要 包括 该 设备 的 管理 包 名 。 


Activity provisioningActivity = getActivity(); 


// You'll need the package name for the WPC app. 
String myWPCPackageName = "com.example.myWPCApp"; 


// Set up the provisioning intent 
Intent provisioningIntent - 
new Intent("android.app.action.PROVISION MANAGED PROFILE"); 
intent.putExtra(myWPCPackageName, 
provisioningActivity.getApplicationContext().getPackageName( )); 


if (provisioningIntent.resolveActivity(provisioningActivity.getPackageManager( ) ) 
-- null) ( 


// No handler for intent! Can't provision this device. 
// Show an error message and cancel. 
} else { 


// REQUEST_PROVISION_MANAGED_PROFILE is defined 
// to be a suitable request code 
startActivityForResult(provisioningIntent, 
REQUEST PROVISION MANAGED PROFILE); 
provisioningActivity.finish(); 


系统 通过 以 下 行为 响应 这 个 intent : 


e 了 验证 设备 是 被 加 密 的。 如 果 没 有 加 密 ， 在 继续 操作 之 前 系统 会 提示 用 户 对 设备 进行 加 


密 。 
e 创建 一 个 managed profile。 
e 从 managed profile 中 移 除 非 必需 的 应 用 。 


e 复制 设备 策略 控制 器 应 用 到 managed profile 中 ， 并 将 设备 策略 控制 器 设置 为 该 profile 
的 所 有 者 。 


如 以 下 实例 代码 所 示 ， 重 写 onActivityResult() 来 查看 部 署 是 否 完成 。 


@Override 
public void onActivityResult(int requestCode, int resultCode, Intent data) { 


// Check if this is the result of the provisioning activity 
if (requestCode == REQUEST PROVISION MANAGED PROFILE) { 


// If provisioning was successful, the result code is 
// Activity.RESULT OK 
if (resultCode == Activity.RESULT OK) { 

// Hurray! Managed profile created and provisioned! 


} else { 
// Boo! Provisioning failed! 


} 


return, 


} else { 
// This is the result of some other activity, call the superclass 


super.onActivityResult(requestCode, resultCode, data); 


创建 Managed Profile 之 后 


当 profile 部 署 完成 ， 系 统 调用 设备 策略 控制 器 应 用 的 
DeviceAdminReceiver.onProfileProvisioningComplete() 方法 。 重 写 该 回调 方法 来 完成 启用 
managed profile ° 


通常 ， 你 的 DeviceAdminReceiver.onProfileProvisioningComplete() 会 执行 这 些 任 务 : 
e 如 建立 设备 政策 所 述 ， 确 认 设 备 遵守 EMM 的 设备 策略 


e 使 用 DevicePolicyManagerenableSystemApp()) 来 启动 管理 员 在 managed profile 中 允 
许 使 用 的 任何 系统 应 用 


e 如 果 设 备 使 用 Google Play for Work， 用 AccountManager.addAccount() 在 managed 
profile 中 添加 Google 账号 ， 管 理 员 就 能 往 设 备 中 安装 应 用 了 。 


一 旦 你 完成 了 这 些 任务 ， 调 用 设备 策略 管理 器 的 setProfileEnabled() 方法 来 激活 managed 
profile : 
// Get the device policy manager 


DevicePolicyManager myDevicePolicyMgr = 
(DevicePolicyManager) getSystemService(Context.DEVICE POLICY SERVICE); 


ComponentName componentName - myDeviceAdminReceiver.getComponentName(this); 


// Set the name for the newly created managed profile. 
myDevicePolicyMgr.setProfileName(componentName, "My New Managed Profile"); 


// ...and enable the profile 
manager.setProfileEnabled(componentName); 


建立 设备 策略 


设备 策略 管理 器 应 用 负责 实行 企业 的 设备 策略 。 例 如 ， 某 个 企业 可 能 需要 在 输 错 一 定 次 数 的 
设备 密码 后 锁定 所 有 设备 。 该 控制 器 应 用 需要 EMM 查 出 当前 的 策略 是 什么 ， 然 后 使 用 设备 管 
理 AP| 来 实行 这 些 策略 。 


更 多 关于 如 何 实行 设备 策略 的 信息 ， 请 查看 设备 管理 指南 。 


实行 应 用 限制 


企业 环境 可 能 需要 那些 批准 的 应 用 实现 安全 性 或 功能 限制 。 应 用 开发 人 员 必 须 实现 这 些 限 
制 ， 并 声明 由 企业 管理 员 使 用 ， 如 实现 应 用 的 限制 所 说 。 设 备 政策 管理 器 接收 来 自 企 业 管 理 
员 改 变 的 限制 ， 并 将 这 些 限制 的 改变 传送 给 相关 应 用 。 


例如 ， 某 个 新 闻 应 用 有 一 个 控制 应 用 是 否 允 许 在 蜂窝 网 络 下 下 载 视频 的 限制 设 定 。 当 EMM 想 
eee ， 它 就 给 控制 器 应 用 发 送 通 知 。 于 是 控制 器 应 用 转 而 通知 新 闻 应 用 限制 设 定 
被 改变 了 。 

EE: 本 文档 涵盖 了 设备 策略 管理 器 应 用 如 何 改 变 managed profile 中 其 他 应 用 的 限制 设 

定 。 关 于 设备 策略 管理 器 应 用 如 何 与 EMM 进行 通讯 的 细节 并 不 在 本 文档 的 范围 之 内 。 

为 了 改变 一 个 应 用 的 限制 ， 调 用 DevicePolicyManager.setApplicationRestrictions() 方法 。 该 
方法 需要 传 入 三 个 参数 : 该 控制 器 应 用 的 DeviceAdminReceiver， 限 制 被 改变 的 应 用 的 包 
名 ， 以 及 包含 了 你 想 要 设置 的 限制 的 Bundle 。 


例如 ， 假 设 managed profile 中 有 一 个 应 用 包 名 是 "com.example.newsfetcher" 。 该 应 用 有 一 
个 布尔 型 限制 可 以 被 配置 ，key 是 "downloadBycellular" 。 如 果 这 个 限制 被 设置 为 false ， 
该 应 用 在 蜂窝 网 络 下 就 不 能 下 载 数据 ， 它 必须 使 用 Wi-Fi 网 络 代 替 。 


如 果 你 的 设备 策略 管理 器 应 用 需要 关 掉 蜂窝 下 载 ， 它 首先 要 取得 设备 策略 服务 对 象 ， 如 上 文 
所 说 。 然 后 集合 一 个 限制 bundle 并 将 该 bundle 传 入 setApplicationRestrictions() : 


// Fetch the DevicePolicyManager 
DevicePolicyManager myDevicePolicyMgr - 
(DevicePolicyManager) thisActivity 
.getSystemService(Context.DEVICE POLICY SERVICE); 


// Set up the restrictions bundle 
bundle restrictionsBundle - new Bundle(); 
restrictionsBundle.putBoolean("downloadByCellular", false); 


// Pass the restrictions to the policy manager. Assume the WPC app 
// already has a DeviceAdminReceiver defined (myDeviceAdminReceiver). 
myDevicePolicyMgr.setApplicationRestrictions( 

myDeviceAdminReceiver, "com.example.newsfetcher", restrictionsBundle); 


注意 : 该 设备 策略 服务 将 限制 改变 传递 给 了 你 所 指定 的 应 用 。 然 而 ， 实 际 是 由 应 用 来 执 
行 该 限制 。 例 如 ， 在 这 个 情况 中 ， 该 应 用 要 负责 禁用 它 本 身 的 使 用 蜂 帘 网 络 下 载 视频 的 
功能 。 设 置 限制 并 不 能 让 系统 强制 在 应 用 上 实现 限制 。 更 多 信息 ， 请 查看 实现 应 用 的 限 
制 。 


Android & 2.7% H 


编写 :kesenhoo - /$ X :http://developer.android.com/training/best-ux.html 


These classes focus on the best Android user experience for your app. In some cases, the 
success of your app on Android is heavily affected by whether your app conforms to the 
user's expectations for UI and navigation on an Android device. Follow these 
recommendations to ensure that your app looks and behaves in a way that satisfies Android 
users. 


Designing Effective Navigation 


How to plan your app's screen hierarchy and forms of navigation so users can effectively 
and intuitively traverse your app content using various navigation patterns. 


Implementing Effective Navigation 


How to implement various navigation patterns such as swipe views, a navigation drawer, 
and up navigation. 


Notifying the User 


How to display messages called notifications outside of your application's UI. 


Adding Search Functionality 


How to properly add a search interface to your app and create a searchable database. 


Making Your App Content Searchable by Google 


How to enable deep linking and indexing of your application content so that users can open 
this content directly from their mobile search results. 


设计 高 效 的 导航 


编写 :XizhiXu - 原文 :http://developer.android.com/training/design-navigation/index.html 


设计 开发 App 的 起 初步 骤 之 一 就 是 决定 用 户 能 够 在 App 上 看 到 什么 和 做 什么 。 一 旦 你 知道 用 
户 在 App 上 和 哪 种 内 容 互 动 ， 下 一 步 就 是 去 设计 容许 用 户 在 App 的 不 同 内 容 块 间 切 换 ， 进 
入 ， 回 退 的 交互 。 


ee ee 适宜 的 导航 形式 来 允许 
用 户 高 效 而 直观 的 浏览 内 容 。 按 粗略 的 先后 顺序 ,每 堂 课 涵 bd 用 导航 交互 设计 过 程 中 
的 不 同 阶段 。 学 过 这 些 课 之 后 ， 你 应 该 可 以 应 用 这 些 列 出 的 方法 和 设计 范例 到 你 自己 的 应 用 
中 ， 为 你 的 用 户 提供 一 致 的 导航 体验 了 。 


Lessons 


e 规划 界面 和 他 们 之 间 的 关系 


学 习 如 何 选择 你 应 用 应 该 包含 的 界面 。 并 且 学 习 如 何 选择 其 他 界面 可 直达 的 界面 。 这 节 
课 介 绍 了 一 个 假想 的 新 闻 应 用 为 以 后 课程 作 例 子 


e 为 多 种 大 小 的 屏幕 进行 规划 
学 习 如 何在 大 屏 设 备 上 组 合 相 关 界 面 来 优化 用 户 可 视界 面 空间 。 
e 提供 向 下 和 横向 导航 


学 习 容 许 用 户 深 入 某 一 层 或 者 在 内 容 层 次 间 横 跨 的 技巧 。 而 且 学 习 一 些 特定 导航 UI 元 素 
在 不 同情 景 下 的 优 缺点 和 最 佳 用 法 。 


e 提供 向 上 和 历史 导航 


学 习 如 何 容 许 用 户 在 内 容 层 级 向 上 导航 。 并 且 学 习 Back 键 和 历史 导航 的 最 佳 做 法 ， 也 即 
导航 到 和 层次 无 关 的 之 前 的 画面 。 


e 综合 : 设计 样 例 App 


学 习 如 何 创 I Wireframe ( 线 框图 ， 模 糊 的 图 形 模 型 ) 来 代表 新 闻 应 用 基于 设想 信 
息 模型 的 界面 。 这 些 Wireframe 利用 上 述 课程 讨论 的 导航 元 件 来 展示 直观 高 效 导 航 。 


规划 界面 和 他 们 之 间 的 关系 


编写 :XizhiXu - Æ x-:http://developer.android.com/training/design-navigation/screen- 
planning.html 


Z 3k App 都 有 一 种 内 在 的 信息 模型 ， 它 能 被 表示 成 一 个 用 对 象 类 型 构成 的 树 或 图 。 更 浅显 的 
说 ， 你 可 以 画 一 个 有 不 同类 型 信息 的 图 ， 这 些 信息 代表 用 户 在 你 App 里 用 户 与 之 互动 的 各 种 
东西 。 软 件 工 程 师 和 数据 架构 师 经 常 使 用 实例 -关系 图 (Entity-Relationship Diagram > ERD) 
普 述 一 个 应 用 的 信息 模型 。 


让 我 们 考虑 一 个 让 用 户 浏览 一 群 已 分 类 好 的 新 闻 事件 和 图 片 的 应 用 例子 。 这 种 App 一 个 可 能 
的 模型 如 下 ERD 图 。 





Saves Saves Contains 


Figure 1. 新 闻 应 用 例子 的 实例 关系 图 








创建 一 个 界面 列表 


一 旦 你 定义 了 信息 模型 ， 你 就 可 以 开始 定义 那些 能 使 用 户 在 你 的 App 中 有 效 地 发 气 ， 查 看 和 
操作 数据 的 上 下 文 环境 了 。 实 际 上 ， 其 中 一 种 方法 就 是 确定 供用 户 导 航 和 交互 数据 所 需 的 界 
面 完 备 集 (归纳 了 所 有 界面 的 集合 ) 。 但 我 们 实际 发 现 的 界面 集合 应 该 根据 目标 设备 变化 。 
在 设计 过 程 中 早点 考虑 到 这 点 很 重要 ， 这 样 可 以 保证 程序 可 以 适应 运行 环境 。 


在 我 们 的 例子 中 ， 我 们 想 让 用 户 查看 ， 保 存 和 分 类 好 了 的 新 闻 和 图 片 。 下 面 是 涵盖 了 这 
些 用 例 的 界面 完备 列表 。 


e 用 来 访问 新 闻 和 图 片 的 Home 或 者 "Launchpad" 画面 
e. 类 别 列表 

e 某 个 分 类 下 的 新 闻 列 表 

e 新 闻 详 情 View (在 这 里 我 们 可 以 保存 和 分 享 ) 

e 图 片 列表 ， 不 分 类 

e 图 片 详 情 View (在 这 里 我 们 可 以 保存 和 分 享 ) 


e 所 有 保存 项 列表 
e 图 片 保 存 列表 
e 新闻 保存 列表 


E] m A d X A 


现在 我 们 可 以 定义 界面 间 的 有 向 关系 了 。 一 个 从 界面 A 指向 另 一 个 界面 已 的 箭头 表示 通过 用 
户 在 画面 A 的 某 个 交互 动作 可 直达 画面 B。 一 旦 我 们 定义 了 界面 集 和 他 们 之 间 的 关系 ， 我 们 
可 以 将 他 们 一 起 全 部 表示 在 一 张 界面 图 中 了 : 











Figure 2. 新 闻 应 用 例子 的 界面 完备 Map 


如 果 之 后 我 们 想 允 许 用 户 提 交 新 闻 事 件 或 者 上 传 图 片 ， 我 们 可 以 在 图 中 加 额外 的 界面 。 


3 A ` ` 
脱离 简陋 设计 

这 时 ， 我 们 可 以 据 这 张 完备 的 界面 图 设计 一 个 功能 完备 应 用 了 。 可 以 由 列表 和 导向 子 界 面 的 
按钮 构成 一 个 简单 的 Ul: 

e 导向 不 同 页 面 的 按钮 (例如 ， 新 闻 ， 图 片 ， 保 存 的 项 目 ) 

e 纵向 列表 表示 集合 (例如 ， 新 闻 列 表 ， 图 片 列 表 ， 等 等 ) 

e 详细 信息 (例如 ， 新 闻 View > AA View ， 等 等 ) 

但 是 ， 你 可 以 利用 屏幕 组 合 技术 和 更 高 深 导 航 元 素 以 一 种 更 直观 ， 设 备 更 理解 的 方式 呈现 内 
容 。 下 节 课 ， 我 们 探索 屏幕 组 合 技术 ， 比 如 为 平板 而 生 的 多 视窗 (Multi-pane) 布局 。 之 后 ， 
我 将 深入 讲解 更 多 不 同 的 Android 常见 导航 模式 。 


下 节 课 : 规划 多 种 触 屏 大 小 


规划 屏幕 界面 与 他 们 之 间 的 关系 
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为 多 种 大 小 的 屏幕 进行 规划 


编写 :XizhiXu - 原文 :http://developer.android.com/training/design-navigation/multiple- 
sizes.html 


虽然 上 节 中 的 界面 完备 图 在 手持 设备 和 相似 大 小 设备 上 可 行 ， 但 并 不 是 和 某 个 设备 因素 绑 死 
的 。Android 应 用 需要 适 配 一 大 把 不 同类 型 的 设备 ， 从 3" 的 手机 到 10" 的 平板 到 42" 的 电视 。 这 
节 课 中 我 们 探讨 把 完备 图 中 不 同 界面 组 合 起 来 的 策略 和 原因 。 

Note: 为 电视 设计 应 用 程序 还 需要 注意 其 他 的 因素 ， 包 括 互动 方式 (就 是 说 ， 它 没 触 


BE) ， 长 距离 情况 下 文本 的 可 读 性 ， 还 有 其 他 的 。 虽 然 这 个 讨论 在 本 课 范 畴 之 外 ， 你 仍 
然 可 以 在 Google TV 文档 的 设计 模式 中 找到 有 关 为 电视 设计 的 信息 。 


多 视窗 布局 (Multi-pane Layout) 组 合 界 面 


多 视窗 布局 (Multi-pane Layout) 设计 
设计 指南 请 阅读 Android 设计 部 分 的 多 视窗 布局 。 


3 到 4 英寸 的 屏幕 通常 只 适合 每 次 展示 单个 纵向 内 容 视窗 ， 一 个 列表 ， 或 某 列 表 项 的 具体 信 
息 ， 等 等 。 所 以 在 这 些 设备 上 ， 界 面 通常 对 映 于 信息 层次 上 的 某 一 级 (类别 一 列表 F 
lt) 。 


更 大 的 诸如 平板 和 电视 上 的 屏幕 通常 会 有 更 多 的 可 用 界面 空间 ， 并 且 他 们 能 够 展示 多 个 内 容 
视窗 。 横 屏 中 ， 视 窗 从 左 到 右 以 细节 程度 递增 的 顺序 排列 。 因 常年 使 用 桌面 应 用 和 网 站 ， 用 
户 变 得 特别 适应 大 屏 上 的 多 视窗 。 很 多 桌面 应 用 和 网 站 提供 左 侧 导航 视窗 ， 或 者 使 用 总 /分 
(master/detail) 两 个 视窗 布局 。 


为 了 符合 这 些 用 户 期 望 ， 通 常 很 有 必要 为 平板 提供 多 个 信息 视窗 来 避免 留 下 过 多 空白 或 无 意 
间 引 入 槛 雁 的 交互 ， 比 如 10 x 0.5" 按钮 。 


下 面 图 例 示范 了 当 把 UI 设计 迁移 到 更 大 的 布局 时 出 现 的 一 些 问题 ， 并 且 展 示 了 如 何 用 多 视 
布局 来 处 理 这 些 问题 : 


Categ 4 
Categ 
Cate ' 
GEBEN) uuu T----------- 
Poor use of 
E in whitespace 


Exceedingly long 
i + line lengths 


图 1. 大 横 屏 使 用 单 视 窗 导 致 槛 碎 的 空白 和 过 长 行 。 


Stories E 












Category 1 Story 1 
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis auctor 
Category - sollicitudin tortor, nec ornare nunc sodales id. Nunc id mi felis. 
Category 3 
Category 4 Story 2 u 
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis auctor 
Category 5 sollicitudin tortor, nec ornare nunc sodales id. Nunc id mi felis 
| Category 6 — -— 
Category 7 Lorem ipsum dolor sit amet, consectetur adipisc 
sollicitudin tortor, nec ornare nunc sodales id. Nunc id mi felis 
Story 4 





Lorem ipsum dolor sit a 
sollicitudin tortor, nec 





ornare 





图 2. 横 屏 多 视窗 布局 产生 更 好 的 视觉 平衡 ， 更 大 的 效用 和 可 读 性 。 


实现 提醒 : 当 决 定好 了 区 分 We 小 基准 线 后 ， 你 就 可 
以 为 不 同 屏 幕 大 小 区 间 (例如 large/xlarge ) 或 最 低 屏 幕 宽度 (例如 sweeodp ) 提供 
不 同 的 布局 了 。 


实现 提醒 : 单一 界面 被 实现 为 Activity 的 子 类 , 单独 的 内 容 视窗 则 可 实现 为 Fragment 的 
子 类 。 这 样 最 大 化 了 跨越 不 同 结构 因素 和 不 同 屏 幕 内容 的 代码 复 用 。 


为 不 同 平板 方向 设计 


虽然 现在 我 们 还 没有 开始 在 我 们 的 屏幕 上 排 布 UI 元 素 ， 但 现在 很 是 时 候 来 考虑 下 我 们 的 多 视 
窗 者 面 如 何 适 配 不 同 的 设备 方向 了 。 多 视窗 布局 在 横 屏 时 表现 的 非常 棒 ， 因 为 有 大 量 可 用 的 
横向 空间 。 然 而 ， 在 坚 屏 时 ， 你 的 横向 空间 被 限制 了 ， 所 以 你 需要 为 这 个 方向 设计 一 个 单独 
的 布局 。 


下 面 是 一 些 创建 坚 屏 布局 的 常见 策略 : 


的 策略 就 是 简单 地 伸缩 每 个 视窗 的 宽度 来 最 好 地 在 坚 屏 下 的 呈现 内 容 。 视 窗 可 设 
宽度 或 占 可 用 界面 宽度 的 一 定 比 例 。 


Www 

视窗 中 左 侧 (master) 视窗 包含 易 折 党 列表 项 时 ， 这 个 策略 很 有 效 。 以 一 个 实时 聊天 应 
用 为 例 。 横 屏 中 ， pick d 包含 聊天 联系 人 的 有 照片， 姓名 和 在 线 状 态 。 在 坚 屏 中 ， 

ee 显示 照片 和 在 线 状态 的 提示 图 标的 方式 来 折 
和 全。 也 可 以 选择 性 的 提供 展开 控制 ， 这 种 控制 允许 用 户 展开 左 侧 视窗 或 反 向 操作 。 


nl | 


这 个 方案 中 ， 左 侧 视窗 在 坚 屏 模式 下 完全 隐藏 。 然而， 为 了 保证 你 界面 的 功能 等 价 性 ， 
左 侧 视 窗 必须 功能 可 见 (比如 ， 添 一 个 按钮 ) 。 通 常 适合 在 Action Bar 使 用 Up 按钮 
( 详 见 Android 设 计 的 模式 文档 ) 来 展示 左 侧 视窗 ， 这 将 在 之 后 讨论 。 


最 直接 
置 固定 


为 多 种 大 小 的 屏幕 进行 规划 


mpm 


最 后 的 策略 就 是 在 坚 屏 时 垂直 地 堆放 你 一 般 横 向 排 布 的 视窗 。 当 你 的 视窗 不 是 简单 的 文 
本 列表 ， 或 者 当 有 多 个 内 容 模 块 与 基本 内 容 视窗 同时 运行 时 ， 这 个 策略 很 奏效 。 但 是 当 
心 使 用 这 个 策略 时 出 现 上 面 提 到 的 槛 碎 的 空白 问题 。 


组 合 界面 图 中 的 界面 


既然 现在 我 们 能 够 通过 提供 大 屏 设 备 上 的 多 视窗 布局 来 组 合 单独 的 界面 ， 那 么 就 让 我 们 把 这 
个 技术 应 用 到 我 们 上 节 课 界面 完备 图 上 吧 ， 这 样 我 们 应 用 的 界面 层次 在 这 类 设备 上 变 得 更 具 
A: 











Figure 3. 更 新 后 新 闻 应 用 例子 的 界面 完备 Map 


下 节 课 我 们 将 讨论 向 下 和 横向 导航 ， 并 且 探 讨 更 多 方法 来 组 合 界面 使 能 最 大 化 应 用 UI 的 直 
观 性 和 内 容 获取 速度 。 


下 一 节 : 提供 向 下 和 横向 导航 
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提供 向 下 与 横向 导航 


编写 :XizhiXu - 原文 :http:/developerandroid.cory/training/design- 
navigation/descendant-lateral.html 


一 种 提供 查看 应 用 整体 界面 结构 的 方式 就 是 显示 层级 导航 。 这 节 课 我 们 讨论 向 下 导航 ， 它 允 
许 用 户 进入 子 界面 。 我 们 还 讨论 横向 导航 ， 它 允许 用 户 访问 同 级 界面 。 


Descendant navigation 





miian ie i 


Lateral navigation 
Figure 1. 向 下 和 横向 导航 


有 两 种 同 jn 容器 关联 和 区 块 关联 界面 。 容 器 关联 (Collection-related) 界面 展示 由 父 界 

面 放 入 同 个 容器 里 地 那些 条 目 。 区 块 关联 (Section-related) 界面 展示 父 界面 不 同 部 分 的 信息 

例如 : dr 分 可 能 展示 某 对 象 的 文字 信息 ， 可 是 另 一 个 部 分 则 提供 对 象 地 理 位 置 的 地 图 。 
父 界 面 的 区 块 关联 界面 数量 通常 较 少 。 





Collection siblings 











Section siblings 


Figure 2. 容器 关联 子 界面 和 区 块 关联 子 界面 。 


向 下 和 横向 导航 可 用 List (FIR) > Tab (标签 ) 或 者 其 他 UI 模式 来 实现 。UI 模式 ,与 软件 设 
计 模 式 很 类 似 ， 是 重复 交互 设计 问题 的 一 般 化 解决 方案 。 下 几 章 ， 我 们 将 探究 一 些 常 用 的 横 
向 导航 模式 。 


Button 和 简单 的 控件 


Buttont it 
设计 指南 请 阅读 Android 设计 文档 的 Button 指 导 


对 于 区 块 关联 的 界面 ， 最 直接 和 熟悉 的 导航 界面 就 是 提供 可 触 或 键盘 可 得 焦点 的 控件 。 例 

如 ，Button， 固 定 大 小 的 List View 或 文本 链接 ， 虽 然后 者 不 是 一 个 触 屏 导 航 的 理想 UI 元 

素 。 一 旦 点 选 了 这 些 控件 ， 子 界面 被 打开 ， 完 全 替代 当前 上 下 文 环境 (屏幕 ) 。Button 或 其 他 
简单 地 控件 很 少 被 用 来 呈现 容器 中 的 项 目 。 





ee Ee 

Section 1 

Section 2 

Section 3 f 
Simple Buttons Dashboard 


Figure 3. Button 寻 航模 式 例子 和 对 应 界面 图 。Dashboard 模式 见 下 文 。 


Dashboard (操作 面板 ) 模式 是 一 种 一 般 以 Button 为 主 来 获取 不 同 应 用 划分 模块 的 模式 。 一 个 
dashboard 就 是 个 大 图 标 Button 表 格 ， 它 表示 了 父 界 面 绝 大 部 分 内 容 。 这 个 表格 通常 是 2、3 行 
或 列 ， 取 决 于 App 的 顶层 划分 。 此 模式 展示 全 部 区 块 的 视觉 效果 非常 丰富 。 巨 大 的 触摸 控件 
也 让 UI 特别 好 使 。 当 每 个 区 块 都 同等 重要 时 ，Dashboard 模 式 最 好 用 。 然 而 ， 这 个 模式 在 大 
屏 上 效果 不 佳 ， 他 让 用 户 直接 获取 App 内 容 时 多 走 了 一 步 弯路 。 


还 有 更 多 套用 了 各 种 其 他 UI 模式 来 提升 内 容 即 得 性 和 独特 的 展示 效果 ， 但 仍 保持 着 直观 特点 
的 高 级 Ul 模式 。 


Lists, Grids, Carousels, and Stacks 


List 和 Grid List 设计 

设计 指南 请 阅读 Android 设计 文档 的 Lists 和 Grid Listsd& $ » 
对 于 容器 关联 的 界面 ， 特 别 是 文字 信息 ， 重 直 滑 动 列 表 通常 是 最 直接 最 熟悉 的 做 法 。 对 于 视 
觉 更 丰富 的 内 容 (例如 ， 图 片 ， 视 频 ) ， 可 用 垂直 滑动 的 Grid， 水 平 滚动 的 List (有 时 被 叫 


做 Carousel) > X, Stack (有 时 叫做 卡片 ，Card) 来 代替 。 这 些 UL 元 素 通 常用 在 呈现 容器 内 
的 条 目 ， 或 大 量子 界面 最 好 ， 而 不 是 零星 的 毫 无 关联 的 同 级 子 界 面 。 








List Grid 


Carousel 


Figure 4. 控件 例子 和 对 应 界面 图 


这 个 模式 还 有 些 问 题 。 深 层 列 表 导 航 常 常 叫 drill-down (444) fL & S4» CHlistz BRE o 
这 种 导航 策 拙 低 效 。 获 得 某 块 内 容 需 要 点 击 多 次 ， 带 给 用 户 很 差 的 体验 ， 特 别 是 活跃 用 户 。 


使 用 纵向 list 也 可 能 带 来 槛 砍 的 用 户 交互 ， 并 且 如 果 |ist 条 目 简 单 地 的 拉 伸 话 也 可 能 用 不 好 大 屏 
空白 。 解 决 方法 就 是 提供 额外 的 信息 ， 例 如 用 文字 汇总 填充 那些 可 用 的 水 平 空间 。 或 者 在 左 
右 添 加 个 视窗 。 


Tabs (标签 ) 


Tab 设计 
设计 指南 请 阅读 Android 设计 文档 的 Tab 指 导 


Tab 是 非常 流行 的 横向 导航 。 这 个 模式 允许 组 合同 级 界面 ， 就 是 说 tab 可 赂 入 原本 可 能 成 为 另 
一 个 界面 的 子 界 面 内 容 。Tab 适 合用 在 小 量 的 区 块 关联 界面 。 
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Figure 5. 手机 和 平板 导航 例子 和 对 应 界面 图 


几 个 使 用 Tab 时 的 最 佳 做 法 。Tab 在 关联 界面 种 应 该 一 直 存 在 ， 只 有 指定 内 容 区 域 发 生 改 变 ， 
并 且 tab 提 示 在 任何 时 候 都 可 用 。 此 外 ，tab 切 换 不 能 算 作 历史 。 例 如 ， 如 果 用 户 从 Tab A 切换 
到 Tab B， 按 Back 按钮 (详情 看 下 节 ) 不 该 重 选 Tab A。Tab 通 常 水 平 排 布 ， 可 是 有 时 其 他 
tab 展 现形 式 ， 例 如 Action bar ( 详 见 Android 设计 的 模式 章节 ) 的 下 拉 菜 单 ， 也 是 可 以 的 。 最 
后 ， 最 重要 的 是 ，tab 应 该 在 界面 顶端 和 内 容 对 应 。 


tab 导 航 相 对 于 list 和 button 导 航 ， 有 很 多 即 得 的 优点 : 
e 既然 只 有 一 个 初始 时 既 选 的 活动 tab， 用 户 能 立即 从 界面 获取 tab 的 内 容 。 
e 用 户 可 在 相关 界面 内 快速 导航 ， 不 用 重新 访问 父 界面 。 


注意 : 当 切 换 Tab 时 ， 保 证 立即 切换 很 重要 。 不 要 加 载 时 弹 个 确认 对 话 框 来 阻塞 tab 
的 访问 。 
导致 这 个 模式 被 批评 常见 的 原因 就 是 必须 从 展示 内 容 的 屏幕 空间 分 一 些 给 tab 提 示 栏 。 但 是 结 
果 还 能 接受 ， 权 衡 一 般 都 向 使 用 此 模式 的 方向 倾斜 。 你 可 以 随意 个 性 化 你 的 tab 提 示 栏 ， 加 点 
文字 或 图 标 什 么 的 让 纵向 空间 合理 利用 。 但 是 调整 tab 宽 度 时 ， 请 确保 tab 够 大 到 能 让 人 无 误 点 
击 。 


水 平分 页 (Swipe View) 


Swipe View 设计 
设计 指南 请 阅读 Android 设计 文档 的 Swipe Views $ 


另 一 种 横向 导航 的 模式 就 是 水 平分 页 ， 也 叫做 Swipe View。 这 个 模式 在 容器 关联 的 同 级 界面 
上 最 好 用 ， 例 如 类 别 列表 (世界 ， 人 金融， 技术 和 健康 新 闻 ) 。 就 像 Tab， 这 个 模式 也 允许 组 合 
KO? 这样 父 界 面 就 能 在 布局 内 谋 入 子 界 面 的 内 容 。 


Horizontal 
Paging 


(screen grouping) 





+ 





Figure 6. 水 平分 页 导航 例子 和 对 应 界面 图 


在 水 平分 页 UI 中， 一 次 只 展示 一 个 子 界面 (这 儿 叫 页 ，page) 。 用 户 能 通过 触摸 屏幕 然后 按 
想 要 访问 相 邻 页 Se ere 同 级 界面 。 为 补充 这 种 手势 交互 通常 由 另 一 种 Ul 元素 提 
示 当 前 页 和 可 访问 页 。 这 样 能 帮助 用 户 发 觉 内 atm Md 更 多 dpa Un 息 给 用 

户 。 copes 这 种 模式 的 水 平 导 航 时 ， 这 个 做 法 很 有 必要 。 这 些 提 示 界 
面 元 素 的 例子 包括 点 标 (tick mark) ， 滑 动 标注 (scrolling label) 和 标签 con 


ELM Tabs 


a Tickmarks 


Friends Labels 





Figure 7. 搭配 分 页 的 Ul 元 件 。 


当 子 界面 包含 水 平平 移 视 图 时 (例如 地 图 ) 也 最 好 避免 使 用 这 种 模式 ， 因 为 这 些 冲突 的 交互 
会 威胁 你 界面 的 易 用 性 。 


此 外 ， 对 于 同 级 关联 界面 ， 如 果 内 容 类 型 具有 一 定 相 似 性 而 且 同 级 界面 数量 较 少时 ， 水 平分 
页 再 适合 不 过 了 。 就 这 一 点 ， 这 个 模式 可 以 和 tab 一 起 用 。tab 放 在 内 容 上 方 来 最 大 化 界面 直观 
性 。 对 于 容器 关联 界面 ， 当 界面 间 有 天 然 的 顺序 时 ， 水 平分 页 是 最 符合 直觉 的 ， 例 如 页 面 代 
表 连 续 的 日 历 日 。 对 于 无 穷 无 尽 的 数据 ， 特 别 是 双向 都 有 内 容 数据 ， 分 页 机 制 效 果 非 常 棒 。 
下 节 课 ， 我 们 讨论 在 内 容 层 级 中 允许 用 户 往 上 和 回 退 到 之 前 访问 界面 的 导航 的 机 制 。 


下 节 课 : 提供 向 上 和 时 间 导 航 


提供 向 上 导航 与 历史 导航 


编写 :XizhiXu - 原文 :http://developer.android.com/training/design-navigation/ancestral- 


temporal.html 
既然 现在 我 们 能 进入 应 用 界面 某 个 层级 ， 我 需要 提供 一 个 方法 来 在 层级 里 向 上 导航 到 父亲 或 
祖先 界面 中 。 此 外 ， 我 们 应 该 保证 通过 Back 按钮 来 回 退 历史 导航 记录 。 

回 退 /向 上 导航 设计 


设计 指南 请 阅读 Android 设计 文档 的 Navigation 模 式 指导 


支持 历史 导航 : Back 


历史 导航 ， 或 者 说 在 历史 的 界面 间 导 航 ， 在 Android 系统 中 由 来 已 久 。 不 论 其 他 状态 如 何 ， 
所 有 Android 用 户 都 期 望 Back 按钮 能 带 他 们 回 到 之 前 的 界面 。 历 史 界 面 集 全 都 以 用 户 的 
Launcher 应 用 为 基础 (电话 的 “Home” 4) 。 也 就 是 说 ， 按 下 Back 键 足够 多 次 数 后 你 应 该 
回 到 Launcher > 之 后 Back 键 不 做 任何 事情 。 


e AR ; 
People Task El T El 


Contacts Contact 
details 


Figure 1. 从 Contacts (KAA) app 中 进入 电子 邮件 app 然后 按 Back 键 的 行为 


应 用 自身 通常 不 必 考 虑 去 管理 Back 按钮 。 系 统 自己 自动 处 理 task 和 back H1H2H3H4 
stack ( 回 退 栈 ) ， 或 者 叫 历史 界面 列表 。 Back 按钮 默认 反 向 访问 界面 列表 ， 然 后 当 按 钮 被 
按 下 时 从 列表 中 移 除 当前 界面 。 


E 


但 是 总 是 有 一 些 你 可 能 需要 重 写 Back 行为 的 例子 。 比 如 ， 你 屏幕 8, — ARCA] PCI] 

| 在 这 个 浏览 器 中 你 的 用 户 可 和 页 面 元 件 进行 交互 来 在 网 页 间 导 航 。 你 可 能 希望 当 用 户 按 
下 设备 的 Back 键 时 触发 嵌入 浏览 器 的 默认 back 操作 。 当 到 达 了 浏览 器 内 部 历史 的 起 始点 ， 
你 就 应 该 遵从 系统 Back 按钮 的 默认 行为 了 。 


提供 向 上 导航 : Up 和 Home 


Android 3.0 之 前 ， 最 常见 的 向 上 导航 的 形式 以 Home 表示 。 大 体 上 是 以 在 设备 Menu 按钮 里 
提供 一 个 Home 的 可 选项 这 样 的 方法 来 实现 ， 或 者 Home 按钮 出 现在 屏幕 的 左上 角 作 为 
Action Barbar (2f JLAndroid 设计 的 模式 章节 ) 的 一 个 组 件 。 当 选中 Home 后 ， 用 户 被 带 到 
界面 层级 的 顶层 ， 通 常 被 叫做 应 用 的 主 界面 。 


oe 全 用 户 一 种 舒适 感 和 安全 感 。 无 论 位 于 应 用 程序 何 处 ， 如 
你 在 App 中 迷路 了 ， 你 可 以 点 选 Me HERG 


Android 3.0 引入 了 Up 记号 ， 它 被 展示 在 了 Action Bar LARA T atig Home 按钮 。 点 击 
UP， 用 户 将 被 带 入 到 结构 中 的 父 界面 。 这 个 导航 操作 通常 就 是 进入 前 一 个 界面 〈 就 像 之 前 
Back 按钮 讨论 中 描述 的 一 样 ) ， 但 是 并 不 是 永远 都 这 样 。 因 此 ， 开 发 者 必须 保证 Up 对 于 每 
个 界面 都 会 导航 到 茶 个 既定 的 父亲 界面 。 


People Task E TET E 


Contacts Contact 
details 


Email Task LO) 


Figure 2. 从 联系 人 App 中 进入 电子 邮件 App 然后 按 Up 导航 的 行为 


某 些 情况 下 ，Up 适合 执行 某 个 行为 而 非 导航 到 一 个 父亲 节点 。 以 Android 3.0 平板 上 的 
Gmail 应 用 为 例 。 当 查看 一 封 邮 件 的 对 话 时 把 设备 平 放 ， 对 话 列表 和 对 话 详 情 将 并 排 显示 。 这 
是 一 种 之 前 课程 中 的 父 、 子 界面 组 合 。 然 而 ， 当 坚 屏 查看 邮件 对 话 时 ， 只 有 对 话 详情 被 显 

T o Up 按钮 被 用 来 使 父 视窗 滑 入 屏幕 显示 。 当 左 侧 视窗 可 见 时 再 按 一 次 Up 按钮 ， 单 个 对 话 
便 回 到 全 屏 的 对 话 列表 中 。 


实现 提醒 : 实现 Home 或 Up 导航 的 最 佳 做 法 就 是 保证 清除 back stack 中 的 子 界面 。 对 

T Home > Home 界面 是 唯一 留 在 back stack 中 的 界面 。 对 于 Up 导航 ， 当 前 界面 也 应 该 
从 back stack 中 移 除 ， 除 非 Back 在 不 同 界面 层级 间 导 航 。 你 可 以 将 

FLAG _ACTIVITY_CLEAR_TOP 和 FLAG ACTIVITY_NEW_TASK 这 两 个 Intent 标记 一 

起 使 用 来 实现 它 。 


最 后 一 节 课 中 ， 我 们 应 用 现在 为 止 所 有 课程 中 讨论 的 概念 来 为 我 们 新 闻 应 用 例子 创建 交互 设 
it Wireframe ( 线 框图 ) 。 


FER: 综合 : 设计 我 们 的 样 例 App 


提供 向 上 和 历史 导航 
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综合 : 设计 我 们 的 样 例 App 


编写 :XizhiXu - 原文 :http://developer.android.com/training/design- 
navigation/wireframing.html 


现在 我 们 对 导航 模式 和 界面 组 合 技术 有 了 深入 的 理解 ， 是 时 候 应 用 到 我 们 的 界面 上 了 。 让 我 
再 看 看 我 们 第 一 节 课 上 提 到 的 新 闻 应 用 的 界面 完备 图 : 





: 
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Figure 1. 新 闻 应 用 例子 的 界面 完备 集 


我 们 下 一 步 得 去 我 们 前 几 节 讨论 的 导航 模式 选择 ， 然 后 应 用 到 这 个 界面 图 中 。 这 样 就 能 最 大 
化 导航 速度 并 且 最 少 化 获取 内 容 的 点 击 次 数 ， 但 又 能 参考 Android 做 法 来 保证 界面 的 直观 性 
和 一 致 性 。 此 外 ， 我 们 也 需要 根据 我 们 不 同 目标 设备 的 参数 做 出 不 同 的 决定 。 为 方便 ， 我 们 
集中 讨论 平板 和 手持 设备 。 


选择 模式 


首先 ， 我 们 二 级 界面 (新闻 类 别 列表 ， 图 片 列表 和 保存 列表 ) 可 用 Tab 组 合 在 一 起 。 注 意 
到 我 们 不 必 使 用 水 平 排列 的 Tab ; 某 些 情况 下 下 拉 菜 单 可 作为 合适 的 替代 品 ， 特 别 在 手机 这 种 
ERRELE. EFWE’ RANEA Tab 把 图 片 保 存 列 表 和 新 闻 保 存 列 表 组 合 到 一 起 ， 或 在 
平板 上 用 多 个 纵向 排列 的 内 容 视窗 。 


最 后 ， 让 我 们 看 看 如 何 展 示 新 闻 。 第 一 个 简化 不 同 新 闻 类 别 间 导航 的 选项 : 使 用 水 平分 页 ， 
然后 再 在 滑动 区 域 上 添加 一 组 标签 来 提示 当前 可 见 和 临近 的 新 闻 类 别 。 对 于 平板 横 屏 ， 我 们 
可 以 进一步 地 展示 能 水 平分 页 的 新 闻 列 表 界面 作为 左边 的 视窗 ， 并 且 把 新 闻 详 情 View 界面 
作为 基础 内 容 视窗 放 在 右边 。 


综合 : 设计 样 例 App 


下 图 分 别 表示 在 手持 设备 和 平板 上 应 用 了 这 些 导 航模 式 后 的 新 界面 图 。 
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Figure 2. 手持 设备 上 新 闻 应 用 例子 的 最 终 界面 集 
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Figure 3. 平板 上 新 闻 应 用 例子 的 最 终 界面 集 ， 横 屏 


至 此 ， 得 好 好 考虑 下 界面 图 的 衍化 了 ， 以 免 我 们 选择 的 模式 实际 上 用 不 了 (比如 当 你 画 应 用 
界面 布局 的 草图 时 ) 。 下 面 有 个 为 平板 衍化 的 界面 图 样 例 ， 它 并 排 展 示 不 同类 别 的 新 闻 列 
表 ， 但 是 新 闻 详 情 View 保持 独立 。 
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Figure 4. 平板 上 新 闻 应 用 例子 的 最 终 界面 集 ， 坚 屏 


E 3-18 


Wireframing 就 是 设计 过 程 中 你 开始 排 布 界面 的 那 步 。 发 挥 你 的 创造 性 ， 想 想 怎么 排列 这 些 UI 


元 件 来 帮助 你 的 用 户 在 你 的 App 中 导航 。 这 时 你 要 记 住 细 梳 末节 是 不 重要 的 ( 别 去 想 着 做 个 
实物 ) 。 


€ kk 


最 简单 快速 的 起 步 方法 就 是 用 纸 笔 手 画 你 界面 。 一 旦 你 开始 画 ， 你 会 发 现在 你 原本 的 界面 图 
或 在 你 决定 使 用 的 模式 中 有 很 多 实际 的 问题 。 某 些 情况 下 ， 模 式 理论 上 能 很 好 的 解决 特定 设 
计 问 题 ， 但 实际 上 他 们 可 能 失效 并 且 给 视觉 交互 添乱 〈( 例 如， 界面 上 出 现 了 两 行 Tab) 。 如 果 
那样 ， 探 索 下 其 他 的 导航 模式 ， 或 在 选择 的 模式 上 做 点 变化 ， 来 让 你 的 草稿 更 优 。 


当 你 对 初稿 满意 后 ， 继 续 用 一 些 软件 画 你 的 数字 wireframe 吧 ， 例 如 : Adobe® Illustrator > 
Adobe® Fireworks，OmniGraffle 或 者 向 量 图 工具 。 选 择 画 图 工具 时 ， 考 虑 以 下 特性 : 


e 能 画 体 现 交 互 的 wireframe A ? 像 Adobe@ Fireworks 就 能 提供 这 个 功能 。 


e 有 界面 “大师” 功能 (允许 不 同 界面 的 视觉 元 素 重用 ) ? 例如 ，Action Bar 必 须 在 你 应 用 的 
每 个 界面 都 出 现 。 


e 学 习 曲 线 怎 样 ? 专业 向 量 图 工具 可 能 有 个 陡峭 的 学 习 曲 线 (RFR) ， 但 有 些 功 能 小 
75 f] wireframing 设计 工具 可 能 更 适合 这 个 任务 。 


最 后 ，XML 布局 编辑 器 ，Android 开发 工具 包 (ADT) 里 面 的 一 个 Eclipse 插件 ， 经 常 被 用 来 
画 草 图 原型 。 但 是 ， 你 应 当 贯 注 于 高 质量 的 布局 而 非 细 节 视 觉 设 计 。 


创建 数字 草图 


在 纸 上 画 完 草 图 并 且 选 择 好 一 款 心仪 的 数字 wireframing 工 具 后 ， 你 可 以 创建 一 个 数字 
wireframe 作 为 你 应 用 视觉 设计 的 起 点 。 下 面 就 是 一 些 我 们 新 闻 客 户 端 Wireframe 例 子 ， 他 们 和 
我 们 之 前 的 界面 图 一 一 对 应 。 





Lorem ipsum dolor sit amet, 
consectetur adipiscing elit. 


Ness r 
Lorem ipsum dolor sit 
amet, consectetur... 
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Figure 5. 新 闻 客 户 端 手机 坚 屏 Wireframe 样 例 (FA SVG 图 ) 



































Figure 6. 新 闻 客 户 端 平板 横 屏 Wireframe 样 例 (FE SVG Bl) 


(下 载 表示 设备 的 Wireframe 的 SVG A) 
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现在 你 已 经 为 你 的 应 用 设计 出 了 高 效 直观 的 App 内 部 导航 ， 你 可 用 开始 花 时 间 来 为 单个 界面 
改善 UI 了 。 例 如 ， 展 示 交 互 内 容 时 ， 你 可 以 选择 使 用 更 花哨 的 控件 来 代替 简单 的 文本 标签 ， 
图 像 和 按钮 。 你 也 可 以 开始 定义 你 应 用 的 视觉 风格 。 在 这 过 程 中 把 你 品牌 的 元 素 作 为 视觉 语 
言 融入 其 中 吧 。 


最 后 ， 也 适时 实现 你 的 设计 吧 ， 使 用 Android SDK 为 你 的 应 用 写 写 代码 。 想 开始 ? 看 看 下 面 
的 这 些 资源 吧 : 


开发 者 指导 : Ul :学 习 如 何 用 Android SDK 实现 你 的 UIAH ° 


e Action Bar :实现 tab， 向 上 导航 ， 屏 幕 上 动作 ， 等 等 。 


e Fragment :实现 可 重用 ， 多 视窗 布局 


支持 库 :用 viewPager 实现 水 平分 页 (Swipe View) 


综合 : 设计 样 例 App 
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编写 :Lin-H - /$ X:http://developer.android.com/training/implementing- 
navigation/index.html 
这 节 课 将 会 演示 如 何 实现 在 Designing Effective Navigation 中 所 详 述 的 关键 导航 设计 模式 。 


在 阅读 这 节 课 程 内 容 之 后 ， 你 VOR E. swipe views, 和 navigation drawer 实 现 导 航 
模式 有 一 个 深刻 的 理解 。 也 会 明白 如 何 提供 合适 的 向 前 向 后 导航 (Up and Back navigation) ° 


Note: 本 节 课 中 的 几 个 元 素 需 要 使 用 Support Library API。 如 果 你 之 前 没有 使 用 过 Support 
Library ， 可 以 按照 Support Library Setup 文 档 说 明 来 使 用 。 


Sample Code 


EffectiveNavigation.zip 


Lessons 


e 使 用 Tabs 创 建 Swipe View 
学 习 如 何在 action bar 中 实现 tab， 并 提供 横向 分 页 (swipe views) 在 tab 之 间 导 航 切 换 。 
e 创建 抽 层 导航 (Navigation Drawer) 


学 习 如 何 建立 隐藏 于 屏幕 边 上 的 界面 ， 通 过 划 屏 (swipe) 或 点 击 action bar 中 的 app 图 标 来 
显示 这 个 界面 。 


e 提供 向 上 导航 
学 习 如 何 使 用 action bar 中 的 app 图 标 实现 向 上 导航 
e 提供 适当 的 向 后 导航 


学 习 如 何 正确 处 理 特殊 情况 下 的 向 后 按钮 (Back button)， 包 括 在 通知 或 app widget 中 的 深 
度 链接 ， 如 何 将 activity 插 入 后 退 栈 (back stack) 中 。 


e 实现 Descendant Navigation 


学 习 更 精细 地 导航 进入 你 的 应 用 信息 层 i 


实现 高 效 的 导航 
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使 用 Tabs 创 建 Swipe 视 图 


编写 :Lin-H - 原文 :http:/developerandroid.comytraining/implementing- 
navigation/lateral.html 
Swipe View 提 供 在 同 级 屏幕 中 的 横向 导航 ， 例 如 通过 横向 划 屏 手势 切换 的 tab( 一 种 称 作 横向 分 
页 的 模式 )。 这 节 课 会 教 你 如 何 使 用 swipe view 创 建 一 个 tab layout 实 现在 tab 之 间 切 换 ， 或 显示 
一 个 标题 条 替代 tab 。 


Swipe View 设计 


在 实现 这 些 功能 之 前 ， 你 要 先 明白 在 Designing Effective Navigation, Swipe Views 
design guide 中 的 概念 和 建议 


实现 Swipe View 


你 可 以 使 用 Support Library 中 的 ViewPager 控 件 在 你 的 app 中 创建 swipe view ° ViewPagerz 
一 个 子 视图 在 layout 上 相互 独立 的 布局 控件 (layout widget) ° 


使 用 ViewPager 来 设置 你 的 layout， 要 添加 一 个 «viewPager» 元 素 到 你 的 XML layout 中 。 例 
如 ， 在 你 的 swipe view 中 如 果 每 一 个 页 面 都 会 占用 整个 layout， 那 么 你 的 layout 应 该 是 这 样 : 


«?xml version="1.0" encoding="utf-8"?> 
«android.support.v4.view.ViewPager 
xmlns:android="http://schemas.android.com/apk/res/android" 
android: id="@+id/pager" 
android: layout_width="match_parent" 
android: layout_height="match_parent" /> 


要 插入 每 一 个 页 面 的 子 视图 ， 你 需要 把 这 个 layout 与 PagerAdapter 挂 钧 。 有 两 种 adapter( 适 配 
器 ) 你 可 以 用 : 


FragmentPagerAdapter 
在 同 级 屏幕 (sibling screen) 只 有 少量 的 几 个 固定 页 面 时 ， 使 用 这 个 最 好 。 
FragmentStatePagerAdapter 


当 根 据 对 象 集 的 数量 来 划分 页 面 ， 即 一 开始 页 面 的 数量 未 确定 时 ， 使 用 这 个 最 好 。 当 用 户 切 
换 到 其 他 页 面 时 ，fragment 会 被 销毁 来 降低 内 存 消 耗 。 


例如 ， 这 里 的 代码 是 当 你 使 用 FragmentStatePagerAdapter 来 在 Fragment 对 象 集合 中 进行 横 
屏 切 换 : 





public class CollectionDemoActivity extends FragmentActivity { 
// 当 被 请 求 时 ， 这 个 adapter 会 返回 一 个 Demo0bjectFragment， 
// 代表 在 对 象 集 中 的 二 个 对 象 : 
DemoCollectionPagerAdapter mDemoCollectionPagerAdapter; 
ViewPager mViewPager; 


public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity collection demo); 


// ViewPager 和 他 的 adapter 使 用 了 support library 
// fragments, 所 以 要 用 getSupportFragmentManager . 
mDemoCollectionPagerAdapter = 
new DemoCollectionPagerAdapter( 
getSupportFragmentManager()); 
mViewPager = (ViewPager) findViewById(R.id.pager); 
mViewPager.setAdapter(mDemoCollectionPagerAdapter); 


// 因为 这 是 一 个 对 象 集 所 以 使 用 FragmentStatePagerAdapter， 
// 而 不 是 FragmentPagerAdapter . 
public class DemoCollectionPagerAdapter extends FragmentStatePagerAdapter { 
public DemoCollectionPagerAdapter(FragmentManager fm) { 
super(fm); 


@Override 

public Fragment getItem(int i) { 
Fragment fragment = new DemoObjectFragment(); 
Bundle args - new Bundle(); 
// 我 们 的 对 象 只 是 一 个 整数 :-P 
args.putInt(DemoObjectFragment.ARG OBJECT, i + 1); 
fragment.setArguments(args); 
return fragment; 


@Override 
public int getCount() { 
íetumnet9g: 


@Override 
public CharSequence getPageTitle(int position) { 
return "OBJECT " + (position + 1); 


// 这 个 类 的 实例 是 一 个 代表 了 数据 集中 一 个 对 象 的 fragment 
public static class DemoObjectFragment extends Fragment { 
public static final String ARG OBJECT - "object"; 


@Override 
public View onCreateView(LayoutInflater inflater, 
ViewGroup container, Bundle savedInstanceState) { 
// 最 后 两 个 参数 保证 LayoutParam 能 被 正确 填充 
View rootView = inflater.inflate( 
R.layout.fragment collection object, container, false); 
Bundle args - getArguments(); 
((TextView) rootView. findViewById(android.R.id.text1)).setText( 
Integer. toString(args.getInt(ARG_OBJECT) )); 
return rootView; 


这 个 例子 只 显示 了 创建 swipe view 的 必要 代码 。 下 面 一 节 向 你 说 明 如 何 通 过 添加 tab 使 导航 更 
方便 在 页 面 间 切换 。 


添加 Tab 到 Action Bar 


ction bar tab 能 给 用 户 提供 更 熟悉 的 界面 来 在 app 的 同 级 屏幕 中 切换 和 分 辩 。 
Action b b 能 给 用 户 提 供 更 熟悉 的 界面 来 在 app 的 同 级 屏幕 中 切换 和 分 辨 


使 用 ActionBar 来 创建 tab， 你 需要 局 用 NAVIGATION_MODE TABS， 然 后 创建 几 
个 ActionBar.Tab 的 实例 ， 并 对 每 个 实例 实现 ActionBarTabListener 接 口 。 例 如 在 你 的 activity 
的 onCreate() 方 法 中 ， 你 可 以 使 用 与 下 面相 似 的 代码 : 


@Override 
public void onCreate(Bundle savedInstanceState) { 
final ActionBar actionBar - getActionBar(); 


// 指定 在 action bar 中 显示 tab . 
actionBar.setNavigationMode(ActionBar.NAVIGATION MODE TABS); 


// 创建 一 个 tab Listener， 在 用 户 切换 tab 时 调用 . 
ActionBar.TabListener tabListener = new ActionBar.TabListener() { 
public void onTabSelected(ActionBar.Tab tab, FragmentTransaction ft) { 
// 显示 指定 的 tab 


public void onTabUnselected(ActionBar.Tab tab, FragmentTransaction ft) { 
// 隐藏 指定 的 tab 


public void onTabReselected(ActionBar.Tab tab, FragmentTransaction ft) { 
// 可 以 忽略 这 个 事件 


un 


// 添加 3 个 tab， 并 指定 tab 的 文字 和 TabListener 
fon Gnt r= op al cs ptt af 
actionBar.addTab( 
actionBar.newTab() 
.setText("Tab " + (i + 1)) 
.setTabListener(tabListener)); 


根据 你 如 何 创 建 你 的 内 容 来 处 理 ActionBar.TabListener 回 调 改变 tab。 但 是 如 果 你 是 像 上 面 那 
样 ， 通 过 ViewPager 对 每 个 tab 使 用 fragment， 下 面 这 节 就 会 说 明 当 用 户 选择 一 个 tab 时 如 何 切 
换 页 面 ， 当 用 户 划 屏 切 换 页 面 时 如 何 更 新 相应 页 面 的 tab。 


使 用 Swipe View 切 换 Tab 


当 用 户 选择 tab 时 ， 在 ViewPager 中 切换 页 面 ， 需 要 实现 ActionBar.TabListener 来 调用 
在 ViewPager 中 的 setCurrentltem() 来 选择 相应 的 页 面 : 


@Override 
public void onCreate(Bundle savedInstanceState) { 


// Create a tab listener that is called when the user changes tabs. 
ActionBar.TabListener tabListener = new ActionBar.TabListener() { 
public void onTabSelected(ActionBar.Tab tab, FragmentTransaction ft) { 
// 当 tab 被 选中 时 ， 切 换 到 ViewPager 中 相应 的 页 面 . 


mViewPager.setCurrentItem(tab.getPosition()); 


un 


同样 的 ， 当 用 户 通过 触 屏 手势 (touch gesture) 切 换 页 面 时 ， 你 也 应 该 选择 相应 的 tab。 你 可 以 
通过 实现 ViewPager.OnPageChangeListener 接 口 来 设置 这 个 操作 ， 当 页 面 变化 时 当前 的 tab 
也 相应 变化 。 例 如 : 


@Override 
public void onCreate(Bundle savedInstanceState) { 


mViewPager - (ViewPager) findViewById(R.id.pager); 
mViewPager .setOnPageChangeListener ( 
new ViewPager .SimpleOnPageChangeListener() { 
@Override 
public void onPageSelected(int position) { 
// 当 划 屏 切 换 页 面 时 ， 选 择 相 应 的 tab. 


getActionBar().setSelectedNavigationItem(position); 


3); 


2 aly 、 
使 用 标题 栏 蔡 代 Tab 
如 果 你 不 想 使 用 action bar tab， 而 想 使 用 scrollable tabs 来 提供 一 个 更 简短 的 可 视 化 配置 ， 你 
可 以 在 swipe view 中 使 用 PagerTitleStrip ° 


下 面 是 一 个 内 容 为 ViewPager， 有 一 个 PagerTitleStrip 顶 端 对 齐 的 activity 的 layout XML 文件 示 
例 。 单 个 页 面 (adapter 提 供 ) 占 据 ViewPager 中 的 剩余 空间 。 


使 用 Tabs 创 建 Swipe 视 图 


«android.support.v4.view.ViewPager 


xmlns:android-"http://schemas.android.com/apk/res/android" 


android: id="@+id/pager" 


android: layout_width="match_parent" 


android: layout_height="match_parent"> 


<android.support.v4.view.PagerTitleStrip 


android 
android 
android 
android 


android: 
android: 
android: 
android: 


:id="@t+id/pager_title_strip" 
: Layout_width="match_parent" 
:layout height-"wrap content" 
:layout gravity-"top" 


background="#33b5e5" 
textColor="#f ff" 
paddingTop="4dp" 
paddingBottom-"4dp" /> 


</android. support.v4.view.ViewPager> 
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创建 抽 层 式 导 航 (navigation drawer) 


编写 :Lin-H - 原文 : http://developer.android.com/training/implementing-navigation/nav- 


drawer.html 


Navigation drawer 是 一 个 在 屏幕 左 侧 边 缘 显 示 导 航 选项 的 面板 。 大 部 分 时 候 是 隐藏 的 ， 当 用 
户 从 屏幕 左 侧 划 屏 ， 或 在 top level 模 式 的 app 中 点 击 action bar 中 的 app 图 标 时 ， 才 会 显示 。 


这 节 课 叙述 如 何 使 用 Support Library 中 的 DrawerLayout API， 来 实现 navigation drawer ° 


Navigation Drawer 设计 : 在 你 决定 在 你 的 app 中 使 用 Navigation Drawer 之 前 ， 你 应 该 
先 理解 在 Navigation Drawer design guide 中 定义 的 使 用 情况 和 设计 准则 。 


创建 一 个 Drawer Layout 


要 添加 一 个 navigation drawer， 在 你 的 用 户 界 面 layout 中 声明 一 个 用 作 root view( 根 视图 ) 的 
DrawerLayout 对 象 。 在 DrawerLayout 中 为 屏幕 添加 一 个 包含 主要 内 容 的 view( 当 drawer 隐 藏 时 
的 主 layout)， 和 其 他 一 些 包 含 nhavigation drawer 内 容 的 view。 


例如 ， 下 面 的 layout 使 用 了 有 两 个 子 视图 (child view) 的 DrawerLayout: 一 个 FrameLayout 用 来 
包含 主要 内 容 ( 在 运行 时 被 Fragment 填 入 )， 和 一 个 navigation drawer 使 用 的 ListView ° 


«android.support.v4.widget.DrawerLayout 


xmlins:android-"http://schemas.android.com/apk/res/android" 
android: id="@+id/drawer_layout" 
android: layout_width="match_parent" 


android: layout_height="match_parent"> 


<!-- 包含 主要 内 容 的 view --> 
«FrameLayout 
android:id-z"Q-id/content frame" 


android: 
android: 


layout width-z"match parent" 
layout height-"match parent" /> 


«!-- navigation drawer( 抽 层 式 导航 ) --» 
«ListView android:id-z"Q-id/left drawer" 


android 
android 
android 
android 
android 
android 


android: 


: Layout_width="240dp" 

:layout height-"match parent" 

:layout gravity-"start" 
:choiceMode="singleChoice" 
:divider="@android:color/transparent" 
:dividerHeight="0dp" 


background="#111"/> 


</android.support.v4.widget .DrawerLayout> 


这 个 layout 展 示 了 一 些 layout 的 重要 特点 : 


e 主 内 容 view( 上 面 的 FrameLayout)， 在 DrawerLayout 中 必须 是 第 一 个 子 视图 ， 因 为 XML 的 
顺序 代表 着 Z 轴 (垂直 于 手机 屏幕 ) 的 顺序 ， 并 且 drawer 必 须 在 内 容 的 前 端 。 


e. 主 内 容 view 被 设置 为 匹配 父 视 图 的 宽 和 高 ， 因 为 当 navigation drawer 隐 藏 时 ， 主 内 容 表 示 
整个 UI 部 分 。 


e drawer 视 图 (ListView) 必 须 使 用 android:layout gravity 属性 指定 它 的 horizontal 
gravity。 为 了 支持 从 右边 阅读 的 语言 (right-to-left(RTL) language)， 指 定 它 的 值 
为 "start" 而 不 是 "left" ( 当 |layout 是 RTL 时 drawer 在 右边 显示 )。 


e drawer 视 图 以 dp 为 单位 指定 它 的 宽 和 高 来 匹配 父 视图 。drawer 的 宽度 不 能 大 于 320dp ， 
这 样 用 户 总 能 看 到 部 分 主 内 容 。 


初始 化 Drawer List 


在 你 的 activity 中 ， 首 先 要 做 的 事 就 是 要 初始 化 drawer 的 item 列 表 。 这 要 根据 你 的 app 内 容 来 处 
理 ， 但 是 一 个 navigation drawer 通 常 由 一 个 ListView 组 成 ， 所 以 列表 应 该 通过 一 个 Adapter( 例 
如 ArrayAdapter 或 SimpleCursorAdapten 填 入 。 


例如 ， 如 何 使 用 一 个 字符 串 数 组 (string array) 来 初始 化 导航 列表 (navigation list): 


public class MainActivity extends Activity { 
private String[] mPlanetTitles; 
private DrawerLayout mDrawerLayout; 
private ListView mDrawerList; 


@Override 

public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity main); 


mPlanetTitles - getResources().getStringArray(R.array.planets array); 
mDrawerLayout - (DrawerLayout) findViewById(R.id.drawer layout); 
mDrawerList = (ListView) findViewById(R.id.left drawer); 


// Alist view Éadapter 

mDrawerList.setAdapter(new ArrayAdapter<String>(this, 
R.layout.drawer list item, mPlanetTitles)); 

// 为 ]ist 设 置 cClick listener 

mDrawerList.setOnItemClickListener(new DrawerItemClickListener()); 


这 段 代码 也 调用 了 setOnltemClickListener() 来 接收 navigation drawer 列 表 的 点 击 事件 。 下 一 节 
会 说 明 如 何 实现 这 个 接口 ， 并 且 当 用 户 选择 一 个 item 时 如 何 改变 内 容 视图 (content view) ° 


处 理 导航 的 点 击 事件 


当 用 户 选择 drawer 列 表 中 的 item， 系 统 会 调用 在 setOnltemClickListener() 中 所 设置 的 
OnltemClickListener 的 onltemClick()。 


在 onltemClick() 方 法 中 做 什么 ， 取 决 于 你 如 何 实现 你 的 app 结 构 (app structure)。 在 下 面 的 例 
子 中 ， 每 选择 一 个 列表 中 的 item， 就 播 入 一 个 不 同 的 Fragment 到 主 内 容 视 图 中 (FrameLayout 
元 素 通过 R.id.content frame ID##72): 


private class DrawerItemClickListener implements ListView.OnItemClickListener { 
@Override 
public void onItemClick(AdapterView parent, View view, int position, long id) { 
selectItem( position); 


/** 在 主 内 容 视图 中 交换 fragment */ 
private void selectItem(int position) { 
// 创建 一 个 新 的 fragment 并 且 根 据 行星 的 位 置 来 显示 
Fragment fragment = new PlanetFragment(); 
Bundle args - new Bundle(); 
args.putInt(PlanetFragment.ARG PLANET NUMBER, position); 


fragment.setArguments(args); 


// 通过 替换 已 存在 的 fragment 来 插入 新 的 fragment 
FragmentManager fragmentManager = getFragmentManager(); 
fragmentManager .beginTransaction() 
.replace(R.id.content frame, fragment) 
.commit(); 
// 高 亮 被 选择 的 Item， 更 新 标题 ， 并 关闭 drawer 
mDrawerList.setItemChecked(position, true); 
setTitle(mPlanetTitles[position]); 
mDrawerLayout.closeDrawer(mDrawerList); 


@Override 

public void setTitle(CharSequence title) { 
mTitle = title; 
getActionBar().setTitle(mTitle); 


监听 打开 和 关闭 事件 


要 监听 drawer 的 打开 和 关闭 事件 ， 在 你 的 DrawerLayout 中 调用 setDrawerListener()， 并 传 入 
一 个 DrawerLayout.DrawerListener 的 实现 。 这 个 接口 提供 drawer 事 件 的 回调 例如 
onDrawerOpened() 和 onDrawerClosed()。 


但 是 ， 如 果 你 的 activity 包 含有 action bar 可 以 不 用 实现 DrawerLayout.DrawerListener， 你 可 以 
继承 ActionBarDrawerToggle 来 替代 。ActionBarDrawerToggle 实 现 了 
DrawerLayout.DrawerListener， 所 以 你 仍然 可 以 重 写 这 些 回调 。 这 么 做 也 能 使 action bar 图 标 
和 navigation drawer 的 交互 操作 变 得 更 容易 (在 下 节 详 述 ) 。 


如 Navigation Drawer design guide 中 所 述 , 当 drawer 可 见 时 ， 你 应 该 修改 action bar 的 内 容 ， 比 
如 改变 标题 和 移 除 与 主 文字 内 容 相关 的 action item。 下 面 的 代码 向 你 说 明 如 何 通 过 
ActionBarDrawerToggle 类 的 实例 ， 重 写 DrawerLayout.DrawerListener 的 回调 方法 来 实现 这 个 
目的 : 


public class MainActivity extends Activity { 
private DrawerLayout mDrawerLayout; 
private ActionBarDrawerToggle mDrawerToggle; 
private CharSequence mDrawerTitle; 
private CharSequence mTitle; 


@Override 

public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity main); 


mTitle - mDrawerTitle - getTitle(); 
mDrawerLayout - (DrawerLayout) findViewById(R.id.drawer layout); 
mDrawerToggle - new ActionBarDrawerToggle(this, mDrawerLayout, 

R.drawable.ic drawer, R.string.drawer open, R.string.drawer close) ( 


/** 当 drawer 处 于 完全 关闭 的 状态 时 调用 */ 

public void onDrawerClosed(View view) { 
super.onDrawerClosed(view); 
getActionBar().setTitle(mTitle); 
invalidateOptionsMenu(); // 创建 对 onPrepareOptionsMenu( ) 的 调 导 


/** 当 drawer 处 于 完全 打开 的 状态 时 调用 */ 

public void onDrawerOpened(View drawerView) { 
super.onDrawerOpened(drawerView); 
getActionBar().setTitle(mDrawerTitle); 
invalidateOptionsMenu(); // 创建 对 onPrepare0ptionsMenu() 的 调用 


un 


// iX &drawer&& & 3 A DrawerListener 
mDrawerLayout.setDrawerListener(mDrawerToggle); 


} 
/* 当 invalidate0ptionsMenu() 调 用 时 调用 */ 
@Override 


public boolean onPrepareOptionsMenu(Menu menu) { 





// 如 果 nav drawer 是 打开 的 ， 隐藏 与 内 容 视图 相关 联 的 action items 
boolean drawerOpen = mDrawerLayout.isDrawerOpen(mDrawerList); 
menu.findItem(R.id.action websearch).setVisible(!drawerOpen); 


return super.onPrepareOptionsMenu(menu); 


下 一 节 会 描述 ActionBarDrawerToggle 的 构造 参数 ， 和 处 理 与 action bar 图 标 交 互 所 需 的 其 他 步 


使 用 App 图 标 来 打开 和 关闭 


用 户 可 以 在 屏幕 左 侧 使 用 划 屏 手势 来 打开 和 关闭 navigation drawer， 但 是 如 果 你 使 用 action 
banm 你 也 应 该 允许 用 户 通过 点 击 app 图 标 来 打开 或 关闭 。 并 且 app 图 标 也 应 该 使 用 一 个 特殊 的 
图 标 来 指明 navigation drawer 的 存在 。 你 可 以 通过 使 用 上 一 节 所 说 的 ActionBarDrawerToggle 
来 实现 所 有 的 这 些 操作 。 


要 使 ActionBarDrawerToggle 起 作用 ， 通 过 它 的 构造 函数 创建 一 个 实例 ， 需 要 用 到 以 下 参数 : 
e Activity 用 来 容纳 drawer ° 
e DrawerLayout ° 


e 一 个 drawable 资 源 用 作 drawer 指 示 器 。 标准 的 navigation drawer T VA # Download the 
Action Bar Icon Pack 获 的 


。 一 个 字符 串 资源 描述 "打开 抽 层 "操作 (便于 访问 ) 
。 一 个 字符 囊 资源 描述 "关闭 抽 层 "操作 (便于 访问 ) 


那么 ， 不 论 你 是 否 创 建 了 用 作 drawer 监 听 器 的 ActionBarDrawerToggle 的 子 类 ， 你 都 需要 在 
activity 生 命 周 期 中 的 某 些 地 方 根据 你 的 ActionBarDrawerToggle 来 调用 。 


public class MainActivity extends Activity { 
private DrawerLayout mDrawerLayout; 
private ActionBarDrawerToggle mDrawerToggle; 


public void onCreate(Bundle savedInstanceState) { 


mDrawerLayout - (DrawerLayout) findViewById(R.id.drawer layout); 
mDrawerToggle - new ActionBarDrawerToggle( 
this, /* AR Activity */ 
mDrawerLayout, /* DrawerLayout *« & */ 
R.drawable.ic drawer, /* nav drawer 图 标 用 来 蔡 换 'Up' 符 号 */ 
R.string.drawer open, /* "打开 drawer" 描述 */ 
R.string.drawer close /* "关闭 drawer" 描述 */ 


) 


/** 当 drawer 处 于 完全 关闭 的 状态 时 调用 */ 

public void onDrawerClosed(View view) { 
super.onDrawerClosed(view); 
getActionBar().setTitle(mTitle); 


/** 当 drawer 处 于 完全 打开 的 状态 时 调用 */ 

public void onDrawerOpened(View drawerView) 1 
super.onDrawerOpened(drawerView); 
getActionBar().setTitle(mDrawerTitle); 


un 


// 设置 drawer 触 发 器 为 DrawerListener 
mDrawerLayout.setDrawerListener(mDrawerToggle); 


getActionBar().setDisplayHomeAsUpEnabled(true); 
getActionBar().setHomeButtonEnabled(true); 


@Override 

protected void onPostCreate(Bundle savedInstanceState) { 
super.onPostCreate(savedInstanceState); 
// 在 onRestoreInstanceState 发 生 后 ， 同 步 触 发 器 状态 ， 
mDrawerToggle.syncState(); 


@Override 

public void onConfigurationChanged(Configuration newConfig) { 
super.onConfigurationChanged(newConfig); 
mDrawerToggle.onConfigurationChanged(newConfig); 


@Override 
public boolean onOptionsItemSelected(MenuItem item) { 
/ 将 事件 传递 给 ActionBarDrawerTogg1le， 如 果 返 回 true， 表 示 app 图 标点 击 事件 已 经 被 处 理 
if (mDrawerToggle.onOptionsItemSelected(item)) { 
return IUe» 


// 处 理 你 的 其 他 action bar items... 


return super.onOptionsItemSelected(item); 


一 个 完整 的 navigation drawer 例 子 ,可 以 在 原文 页 面 顶 端的 Sample 下 载 


提供 向 上 的 导航 


编写 :Lin-H - 原文 :http:/developerandroid.comytraining/implementing- 
navigation/ancestral.html 


所 有 不 是 从 主屏 幕 ("home" 屏 幕 ) 进 入 app 的 ， 都 应 该 给 用 户 提 供 一 种 方法 ， 通 过 点 击 action bar 
中 的 Up 按钮 。 可 以 回 到 app 的 结构 层次 中 逻辑 父 屏幕 。 本 课程 向 你 说 明 如 何 正确 地 实现 这 一 
操作 。 

Up Navigation 设计 

Designing Effective Navigation 和 the Navigation design guide 中 描述 了 向 上 导航 的 概念 

和 设计 准则 。 


《 o Screen Title 


Figure 1. action bar 中 的 Up 按钮 . 


指定 父 Activity 


要 实现 向 上 导航 ， 第 一 步 就 是 为 每 一 个 activity 声 明 合适 的 父 activity。 这 么 做 可 以 使 系统 简化 
导航 模式 ， 例 如 向 上 导航 ， 因 为 系统 可 以 从 manifest 文 件 中 判断 它 的 逻辑 父 (logical 
parent)activity ° 

从 Android 4.1 (API level 16) 开 始 ， 你 可 以 通过 指定 <activity> 元 素 中 的 
android:parentActivityName 属 性 来 声明 每 一 个 activity 的 逻辑 父 activity ° 

如 果 你 的 app 需 要 支持 Android 4.0 以 下 版 本 ， 在 你 的 app 中 包含 Support Library 并 添加 <meta- 


data» 元 素 到 «activity» 中 。 然 后 指定 父 activity 的 值 为 android.support.PARENT ACTIVITY ， 
并 匹配 android:parentActivityName 的 值 。 


例如 : 


«application ... » 


«!-- main/home activity (没有 父 activity) --> 


«activity 
android:name="com.example.myfirstapp.MainActivity" ...> 

</activity> 

<!-- 主 activity 的 一 个 子 activity --> 

«activity 


android:name="com.example.myfirstapp.DisplayMessageActivity" 
android:label-"Qstring/title activity display message" 
android:parentActivityName-"com.example.myfirstapp.MainActivity" » 
«!-- 父 activity 的 meta-data， 用 来 支持 4.0 以 下 版 本 --> 
<meta-data 
android:name-"android.support.PARENT ACTIVITY" 
android: value="com.example.myfirstapp.MainActivity" /> 
</activity> 
</application> 


在 父 activity 这 样 声明 后 ， 你 可 以 使 用 NavUtils API 进 行 向 上 导航 操作 ， 就 像 下 一 面 这 节 。 


添加 向 上 操作 (Up Action) 
要 使 用 action bar 的 app 图 标 来 完成 向 上 导航 ， 需 要 调用 setDisplayjHomeAsUpEnabled(): 


@Override 
public void onCreate(Bundle savedInstanceState) { 


getActionBar().setDisplayHomeAsUpEnabled( true); 


这 样 ， 在 app 旁 添加 了 一 个 左 向 符号 ， 并 用 作 操 作 按 钮 。 当 用 户 点 击 它 时 ， 你 的 activity 会 接收 
一 个 对 onOptionsltemSelected() 的 调用 。 操 作 的 ID 是 android.R.id.home ° 


向 上 导航 至 父 activity 


要 在 用 户 点 击 app 图 标 时 向 上 导航 ， 你 可 以 使 用 NavUtils 类 中 的 静态 方法 
navigateUpFromSameTask()。 当 你 调用 这 一 方法 时 ， 系 统 会 结束 当前 的 activity 并 启动 (或 恢 
复 ) 相 应 的 父 activity。 如 果 目 标 activity 在 任务 的 后 退 栈 中 (back stack)， 则 目标 activity 会 像 
FLAG_ACTIVITY_CLEAR_TOP 定 义 的 那样 ， 提 到 栈 顶 。 提 到 栈 顶 的 方式 取决 于 父 activity 是 
否 处 理 了 对 onNewlntent() 的 调用 。 


例如 : 


@Override 
public boolean onOptionsItemSelected(MenuItem item) { 
switch (item.getItemId()) ( 
// 对 action bar 的 Up/Home 按 钮 做 出 反应 
case android.R.id.home: 
NavUtils.navigateUpFromSameTask(this); 
recurn e 


} 


return super.onOptionsItemSelected(item); 


但 是 ， 只 能 是 当 你 的 app 拥 有 当前 任务 (current task)( 用 户 从 你 的 app 中 发 起 这 一 任务 ) 时 
navigateUpFromSameTask() 才 有 用 。 如 果 你 的 activity 是 从 别 的 app 的 任务 中 启动 的 话 ， 向 上 
导航 操作 就 应 该 创建 一 个 属于 你 的 app 的 新 任务 ， 并 需要 你 创建 一 个 新 的 后 退 栈 。 


用 新 的 后 退 栈 来 向 上 导航 


如 果 你 的 activity 提 供 了 任何 允许 被 别 的 app 局 动 的 intent filters， 那 么 你 应 该 实现 
onOptionsltemSelected() 回 调 ， 在 用 户 从 别 的 app 任 务 进入 你 的 activity 后 ， 点 击 Up 按 钮 ， 在 
向 上 导航 之 前 你 的 app 用 相应 的 后 退 栈 开启 一 个 新 的 任务 。 


在 这 么 做 之 前 ， 你 可 以 先 调用 shouldUpRecreateTask() 来 检查 当前 的 activity 实 例 是 否 在 另 一 
个 不 同 的 app 任 务 中 。 如 果 返 回 true， 就 使 用 TaskStackBuilder 创 建 一 个 新 任务 。 或 者 ， 你 可 
以 向 上 面 那样 使 用 navigateUpFromSameTask() 方 法 。 


例如 : 


提供 向 上 的 导航 


@Override 
public boolean onOptionsItemSelected(MenuItem item) { 
switch (item.getItemId()) ( 
// 对 action bar&jUp/Home4z 44K h & 
case android.R.id.home: 
Intent upIntent - NavUtils.getParentActivityIntent(this); 
if (NavUtils.shouldUpRecreateTask(this, upIntent)) { 
// 这 个 activity 不 是 这 个 app 任 务 的 一 部 分 ， 所 以 当 向 上 导航 时 创建 
// 用 合成 后 退 栈 (Synthesized back stack) 创 建 一 个 新 任务 。 
TaskStackBuilder.create(this) 
// 添加 这 个 activity 的 所 有 父 Qctivity 到 后 退 栈 中 
.addNextIntentWithParentStack(upIntent) 
// 向 上 导航 到 最 近 的 一 个 父 activity 
.startActivities(); 
else { 
// 这 个 activity 是 这 个 app 任 务 的 一 部 分 ， 所 以 
// 向 上 导航 至 逻辑 父 activity . 
NavUtils.navigateUpTo(this, upIntent); 
} 


return true; 


} 


return super.onOptionsItemSelected(item); 


Note: 为 了 能 使 addNextlntentWithParentStack() 方 法 起 作用 ， 你 必须 像 上 面 说 的 那样 ， 
在 你 的 manifest 文 件 中 使 用 android:parentActivityName( 和 相应 的 «meta-data» 元 素 ) 属 性 
声明 所 有 的 activity 的 逻辑 父 activity ° 
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提供 向 后 的 导航 


编写 :Lin-H - /$ x-:http://developer.android.com/training/implementing- 
navigation/temporal.html 


向 后 导航 (Back navigation) 是 用 户 根据 屏幕 历史 记录 返回 之 前 所 查看 的 界面 。 所 有 Android 设 
备 都 可 以 为 这 种 导航 提供 后 退 按钮 ， 所 以 你 的 app 不 需要 在 UI 中 添加 后 退 按钮 。 


在 几乎 所 有 情况 下 ， 当 用 户 在 应 用 中 进行 导航 时 ， 系 统 会 保存 activity 的 后 退 栈 。 这 样 当 用 户 
点 击 后 退 按钮 时 ， 系 统 可 以 正确 地 向 后 导航 。 但 是 ， 有 少数 几 种 情况 需要 手动 指定 app 的 后 退 
操作 ， 来 提供 更 好 的 用 户 体验 。 


Back Navigation 人 设计 


在 继续 阅 He 文章 之 前 ， 你 应 该 先 在 Navigation design guide 中 对 后 退 导航 的 概念 和 设计 
准则 有 个 了 解 


手动 指定 后 退 操作 需要 的 导航 模式 : 
e 当 用 户 从 notification( 通 知 )，app widget > navigation drawer 直 接 进 入 深层 次 activity » 
e 用 户 在 fragment 之 间 切 换 的 某 些 情况 。 
e 当 用 户 在 WebView 中 对 网 页 进行 导航 。 


下 面 说 明 如 何在 这 几 种 情况 下 实现 恰当 的 向 后 导航 。 


为 深度 链接 合并 新 的 后 退 栈 


一 般 而 言 ， 当 用 户 从 一 个 activity 导 航 到 下 一 个 时 ， 系 统 会 递增 地 创建 后 退 栈 。 但 是 当 用 户 从 
一 个 在 自己 的 任务 中 启动 activity 的 深度 链接 进入 app， 你 就 有 必要 去 同步 新 的 后 退 栈 ， 因 为 新 
的 activity 是 运行 在 一 个 没有 任何 后 退 栈 的 任务 中 。 

例如 ， 当 用 户 从 通知 进入 你 的 app 中 的 深层 activity 时 ， 你 应 该 添加 别 的 activity 到 你 的 任务 的 后 
退 栈 中 ， 这 样 当 点 击 后 退 (Back) 时 向 上 导航 ， 而 不 是 退出 app。 这 个 模式 在 Navigation design 
guide 中 有 更 详细 的 介绍 。 


在 manifest 中 指定 父 activity 


从 Android 4.1 (API level 16) 开 始 ， 你 可 以 通过 指定 <activity> 元 素 中 的 
android:parentActivityName 属 性 来 声明 每 一 个 activity 的 逻辑 父 activity。 这 样 系统 可 以 使 导航 
模式 变 得 更 容易 ， 因 为 系统 可 以 根据 这 些 信息 判断 逻辑 Back Up navigation 的 路 径 。 


如 果 你 的 app 需 要 支持 Android 4.0 以 下 版 本 ， 在 你 的 app 中 包含 Support Library 并 添加 <meta- 
data» 元 素 到 «activity» 中 。 然 后 指定 父 activity 的 值 为 android.support.PARENT ACTIVITY ^ 
并 匹配 android:parentActivityName 的 值 。 


例如 : 
«application ... » 
<!-- main/home activity (没有 父 activity) --> 
«activity 
android:name="com.example.myfirstapp.MainActivity" ...> 
</activity> 
<!-- 主 activity 的 一 个 子 activity --> 
«activity 
android:name="com.example.myfirstapp.DisplayMessageActivity" 
android:label-"Qstring/title activity display message" 
android:parentActivityName-"com.example.myfirstapp.MainActivity" » 
<!-- 4.1 以 下 的 版 本 需要 使 用 meta-data 元 素 --» 
<meta-data 
android:name-"android.support.PARENT ACTIVITY" 
android:value-"com.example.myfirstapp.MainActivity" /> 
«/activity» 
</application> 


当 父 activity 用 这 种 方式 声明 ， 你 就 可 以 使 用 NavUtils API， 通 过 确定 每 个 activity 相 应 的 父 
activity 来 同步 新 的 后 退 栈 。 


在 启动 activity 时 创建 后 退 栈 


在 发 生 用 户 进入 app 的 事件 时 ， 开 始 添加 activity 到 后 退 栈 中 。 就 是 说 ， 使 用 TaskStackBuilder 
API 定 义 每 个 被 放 到 新 后 退 栈 的 activity， 不 使 用 startActivity()。 然 后 调用 startActivities() 来 局 
动 目标 activity， 或 调用 getPendinglntent() 来 创建 相应 的 Pendinglntent 。 


例如 ， 当 用 户 从 通知 进入 你 的 app 中 的 深层 activity 时 ， 你 可 以 使 用 这 段 代 码 来 创建 一 个 启动 
activity 并 把 新 后 退 栈 插入 目标 任务 的 Pendinglntent 。 


// 当 用 户 选择 通知 时 ， 启 动 activity 的 jntent 
Intent detailsIntent = new Intent(this, DetailsActivity.class); 


// 使 用 TaskStackBuilder 创 建 后 退 栈 ， 并 获取 PendingIntent 
PendingIntent pendingIntent = 
TaskStackBuilder.create(this) 
// 添加 所 有 DetailsActivity 的 父 Qctivity 到 栈 中 ， 
// 然后 再 添加 DetailsActivity 自 己 
.addNextIntentWithParentStack(upIntent) 
.getPendingIntent(0, PendingIntent.FLAG UPDATE CURRENT); 


NotificationCompat.Builder builder - new NotificationCompat.Builder(this); 
builder.setContentIntent(pendingIntent); 


产生 的 Pendinglntent 不 仅 指 定 了 启动 哪个 activity( 被 detailsIntent 所 定义 ) 还 指定 了 要 插入 任 
务 ( 所 有 被 detailsIntent 定义 的 DetailsActivity ) 的 后 退 栈 。 所 以 当 petailsActivity 启动 
时 ， 点 击 Back 向 后 导航 至 每 一 个 Detailsactivity 类 的 父 activity。 


Note: 为 了 使 addNextlntentWithParentStack() 方 法 起 作用 ， 像 上 面 所 说 那样 ， 你 必须 在 
你 的 manifest 文 件 中 使 用 android:parentActivityName( 和 相应 的 元 素 <meta-data> ) 属 性 声 
明 每 个 activity 的 逻辑 父 activity ° 


为 Fragment 实 现 向 后 导航 


当 在 app 中 使 用 fagment 时 ， 个 别 的 FragmentTransaction 对 象 可 以 代表 要 加 入 后 退 栈 中 变化 
的 内 容 。 例 如 ， 如 果 你 要 在 手机 上 通过 交换 fragment 实 现 一 个 master/detail flow( 主 /详细 流 
程 )， 你 就 要 保证 点 击 Back 按 钮 可 以 从 detail screen 返 回 到 master screen。 要 这 么 做 ， 你 可 以 
在 提交 事务 (transaction) 之 前 调用 addToBackStack(): 


// 使 用 framework FragmentManager 

// 或 support package FragmentManager (getSupportFragmentManager ). 

getSupportFragmentManager ( ).beginTransaction() 
.add(detailFragment, "detail") 


// 提交 这 一 事务 到 后 退 栈 中 
.addToBackStack() 
.commit(); 


当 后 退 栈 中 有 FragmentTransaction 对 象 并 且 用 户 点 击 Back 按 钮 时 ,FragmentManager 会 从 后 
退 栈 中 弹出 最 近 的 事务 ， 然 后 执行 反 向 操作 (例如 如 果 事 务 添 加 了 一 个 fragment， 那 么 就 删除 
一 个 fragment)。 


Note: 当 事务 用 作 水 平 导 航 (例如 切换 tab) 或 者 修改 内 容 外 观 (例如 在 调整 filter 时 ) 时 ， 不 要 
这 个 事务 添加 到 后 退 栈 中 。 更 多 关于 向 后 导航 的 恰当 时 间 的 信息 ， 详 见 Navigation 
hil guide ° 


如 果 你 的 应 用 更 新 了 别 的 Ul 元 素来 反应 当前 的 fagment 状 态 ， 例 如 action bar， 记 得 当 你 提交 
事务 时 更 新 Ul。 除 了 在 提交 事务 的 时 候 ， 在 后 退 栈 发 生变 化 时 也 要 更 新 你 的 Ul。 你 可 以 设置 

一 个 FragmentManagerOnBackStackChangedListener 来 监听 FragmentTransaction 什 么 时 候 
复原 : 


getSupportFragmentManager ( ).addOnBackStackChangedListener( 
new FragmentManager.OnBackStackChangedListener() { 
public void onBackStackChanged() { 
// 在 这 里 更 新 你 的 UI 
} 
}); 


为 WebView 实 现 向 后 导航 


如 果 你 的 应 用 的 一 部 分 包含 在 WebView 中 ， 可 以 通过 浏览 器 历史 使 用 Back。 要 这 么 做 ， 如 果 
WebView 有 历史 记录 ， 你 可 以 重 写 onBackPressed() 并 代理 给 WebView: 


@Override 
public void onBackPressed() { 
if (mWebView.canGoBack()) { 
mwebView.goBack(); 
return; 


} 


// 否则 遵从 系统 的 默认 操作 . 
super.onBackPressed(); 


要 注意 当 使 用 这 一 机 制 时 ， 高 动态 化 的 页 面 会 产生 大 量 历史 。 会 生成 大 量 历史 的 页 面 ， 例 如 
经 常 改 变 文件 散 列 (document hash) 的 页 面 , 当 要 退出 你 的 activity 时 ， 这 会 使 你 的 用 户 感到 繁 
B e 


更 多 关于 使 用 WebView 的 信息 ， 详 见 Building Web Apps in WebView ° 


实现 向 下 的 导航 


编写 :Lin-H - /% X:http://developer.android.com/training/implementing- 
navigation/descendant.html 


Descendant Navigation 是 用 来 向 下 导航 至 应 用 的 信息 层次 。 在 Designing Effective Navigation 
和 Android Design: Application Structure 中 说 明 。 


Descendant navigation 通 常 使 用 WU 实现 ， 或 使 用 FragmentTransaction 对 象 
添加 fragment 到 一 个 activity 中 。 这 节 课 程 涵盖 了 在 实现 Descendant navigation 时 遇 到 的 其 他 
有 趣 的 情况 。 


在 手机 和 平板 (Tablet) 上 实现 Master/Detail Flow 


在 master/detail 导 航 流程 (navigation flow)? > master screen( 主 屏幕 ) 包 含 一 个 集合 中 item 的 列 
表 ，detail screen( 详 细 屏 幕 ) 显 示 集合 中 特定 item 的 详细 信息 。 实 现 从 master screen! detail 
screen 的 导航 是 Descendant Navigation 的 一 种 形式 。 


手机 触摸 屏 非 常 适合 一 次 显示 一 种 屏幕 (master screen 或 detail screen) ; 这 一 想法 在 Planning 
for Multiple Touchscreen Sizes 中 进一步 说 明 。 在 这 种 情况 下 ， 一 般 使 用 Intent 启 动 detail 
screen 来 实现 activityDescendant navigation。 另 一 方面 ， 平 板 的 显示 ， 特 别 是 用 横 屏 来 浏览 
时 ， 最 适合 一 次 显示 多 个 内 容 窗 格 ，master 内 容 在 左边 ，detail 在 右边 。 在 这 里 一 般 就 使 

用 FragmentTransaction 实 现 descendant navigation ° FragmentTransaction ff] K Z& Zu ` M RER 
用 新 内 容 替 换 detail 窗 格 (pane)。 


实现 这 一 模式 的 基础 内 容 在 Designing for Multiple Screens 的 Implementing Adaptive UI Flows 
课程 中 说 明 。 课 程 中 说 明了 如 何在 手机 上 使 用 两 个 activity， 在 平板 上 使 用 一 个 activity 来 实现 
master/detail flow ° 


导航 至 外 部 Activities 


有 很 多 情况 ， 是 从 别 的 应 用 下 降 (descend) 至 你 的 应 用 信息 层次 (application's information 
hierarchy) 再 到 activity。 例 如 ， 当 正在 浏览 a 系 信息 的 details screen， 子 屏幕 详 
细 显 示 由 社交 网 络 联系 提供 的 最 近 文 章 ， 子 屏幕 可 就 可 以 属于 一 个 社交 网 络 应 用 。 


当 启 动 另 一 个 应 用 的 activity 来 允许 用 户 说 话 ， 发 邮件 或 选择 一 个 照片 附件 ， 如 果 用 户 是 从 启 
动 器 (设备 的 home 屏 划 ] 重 局 你 的 应 用 ， 你 一 般 不 会 SECURUM 如 果 点 击 你 
的 应 用 图 标 又 回 到 “发 邮件 "的 屏幕 ， 这 会 使 用 户 感到 很 迷 


为 防止 这 种 情况 的 发 生 ， 只 需要 添加 FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET 标 记 
到 用 来 启动 外 部 activity 的 intent 中 ， 就 像 : 


Intent externalActivityIntent = new Intent(Intent.ACTION PICK); 
externalActivityIntent.setType("image/*"); 
externalActivityIntent.addFlags( 

Intent.FLAG ACTIVITY CLEAR WHEN TASK RESET); 


startActivity(externalActivityIntent); 





s2 日 -一 
通知 提示 用 户 
编写 :fastcome1985 - 原文 :http://developer.android.com/training/notify-user/index.html 


e Notification 是 一 种 在 你 APP 常 规 UI 外 展示 、 用 来 指示 某 个 事件 发 生 的 用 户 交 互 元 素 。 用 
户 可 以 在 使 用 其 它 apps 时 查看 notification， 并 在 方便 的 时 候 做 出 回应 。 


e Notification 设 计 指 导向 你 展示 如 何 设 计 实 用 的 notifications 以 及 何 时 使 用 它们 。 这 节 课 将 
会 教 你 实现 大 多 数 常用 的 notification 设 计 。 


e 完整 的 Demo 示 例 : NotifyUser.zip 


Lessons 


e 建立 一 个 Notification 
学 习 如 何 创建 一 个 notification Builder， 设 置 需要 的 特征 ， 以 及 发 布 notification ° 
e 当 Activity 启 动 时 保留 导航 
学 习 如 何 为 一 个 从 notification 启 动 的 Activity 执 行 适当 的 导航 。 
e 更 新 notifications 
学 习 如 何 更 新 与 移 除 notifications 
e 使 用 BigView 风 格 
学 习 用 扩展 的 notification 来 创建 一 个 BigView， 并 且 维 持 老 版 本 的 兼容 性 。 
e 显示 notification 进 度 


学 习 在 notification 中 显示 某 个 操作 的 进度 ， 既 可 以 用 于 那些 你 可 以 估算 已 经 完成 多 少 ( 确 
定 进度 ，determinate ) 的 操作 ， 也 可 以 用 于 那些 你 无 法 知道 完成 了 多 少 (不 确定 进度 ， 
indefinite ) 的 操作 


建立 一 个 Notification 


编写 :fastcome1985 - Æ X:http://developer.android.com/training/notify-user/build- 
notification.html 


e 这 节 课 向 你 说 明 如 何 创 建 与 发 布 一 个 Notification ° 


e 这 节 课 的 例子 是 基于 NotificationCompat.Builder 类 的 ，NotificationCompat.Builder 
在 Support Library 中 。 为 了 给 许多 各 种 不 同 的 平台 提供 最 好 的 notification 支 持 ， 你 应 该 使 
用 NotificationCompat 以 及 它 的 子 类 ， 特 别 是 NotificationCompat.Builder ° 


创建 Notification Buider 


e 创建 Notification 时 ， 可 以 用 NotificationCompat.Builder 对 象 指定 Notification 的 UI 内 容 与 行 
为 。 一 个 Builder 至 少 包 含 以 下 内 容 : 


o 一 个 小 的 icon， 用 setSmalllcon()) 方 法 设置 
o 一 个 标题 ， 用 setContentTitle()) 方 法 设置 。 
o 详细 的 文本 ， 用 setContentText()) 方 法 设置 


例如 : 


NotificationCompat.Builder mBuilder = 
new NotificationCompat.Builder(this) 
.setsmallIcon(R.drawable.notification icon) 
.setContentTitle("My notification") 
.setContentText("Hello World!"); 


æ 3 Notification&? Action (行为 ) 


e 尽管 在 Notification 中 Actions 是 可 选 的 ， 但 是 你 应 该 至 少 添加 一 种 Action。 一 种 Action 可 以 
让 用 户 从 Notification 直 接 进 入 你 应 用 内 的 Activity， 在 这 个 activity 中 他 们 可 以 查看 引起 
Notification 的 事件 或 者 做 下 一 步 的 处 理 。 在 Notification 中 ，action 本 身 是 由 Pendinglntent 
定义 的 ，Pendinglntent 包 含 了 一 个 启动 你 应 用 内 Activity 的 Intent 。 


e 如 何 构建 一 个 Pendinglntent 取 决 于 你 要 局 动 的 activity 的 类 型 。 当 从 Notification 中 局 动 一 
个 activity 时 ， 你 必须 保存 用 户 的 导航 体验 。 在 下 面 的 代码 片段 中 ， 点 击 Notification 启 动 
一 个 新 的 activity， 这 个 activity 有 效 地 扩展 了 Notification 的 行为 。 在 这 种 情形 下 ， 就 没 必 


要 人 为 地 去 创建 一 个 返回 栈 (更 多 关于 这 方面 的 信息 ， 请 查看 Preserving Navigation 
when Starting an Activity ) 


Intent resultIntent - new Intent(this, ResultActivity.class); 


// Because clicking the notification opens a new ("special") activity, there's 
// no need to create an artificial back stack. 
PendingIntent resultPendingIntent - 

PendingIntent.getActivity( 

this, 

9, 

resultIntent, 

PendingIntent.FLAG UPDATE CURRENT 
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可 以 通过 调用 NotificationCompat.Builder 中 合适 的 方法 ， 将 上 一 步 创 建 的 Pendinglntent 与 一 
个 手势 产生 关联 。 比 方 说 ， 当 点 击 Notification 抽 层 里 的 Notification 文 本 时 ， 局 动 一 个 activity > 
可 以 通过 调用 setContentlntent()) 方 法 把 Pendinglntent 添 加 进去 。 


例如 : 


PendingIntent resultPendingIntent; 


mBuilder.setContentIntent(resultPendingIntent); 


E "s Notification 
为 了 发 布 notification : 


* 获取 一 个 [NotificationManager](http://www.baidu.com/baidu?wd=NotificationManager.&tn=mo 
nline_4_dg) 实 例 

* 使 用 [notify()](developer.android.com/reference/java/lang/0bject.html#notify()) 方 法 发 布 
Notification。 当 你 调用 [notify()](developer.android.com/reference/java/lang/0bject.html#n 
otify()) 方 法 时 ， 指 定 一 个 hotification ID。 你 可 以 在 以 后 使 用 这 个 ID 来 更 新 你 的 notification。 这 在 [Man 
aging Notifications](developer.android.com/intl/zh-cn/training/notify-user/managing.ht 
m1) 中 有 更 详细 的 描述 。 

* 调用 [build()](developer.android.com/reference/android/support/v4/app/NotificationComp 
at .Builder .html#build()) 方 法 ， 会 返回 一 个 包含 你 的 特征 的 [Notification] (developer.android.com/ 
reference/android/app/Notification.html)s £& ° 


举 个 例子 : 


NotificationCompat.Builder mBuilder; 


// Sets an ID for the notification 
int mNotificationId = 001; 
// Gets an instance of the NotificationManager service 
NotificationManager mNotifyMgr = 

(NotificationManager) getSystemService(NOTIFICATION SERVICE); 
// Builds the notification and issues it. 
mNotifyMgr.notify(mNotificationId, mBuilder.build()); 


后 动 Activity 时 保留 导航 


编写 :fastcome1985 - 原文 :http://developer.android.com/training/notify- 
user/navigation.html 


部 分 设计 一 个 notification 的 目的 是 为 了 保持 用 户 的 导航 体验 。 为 了 详细 讨论 这 个 课题 ， 请 看 
Notifications API1 引 导 ， 分 为 下 列 两 种 主要 情况 : 


* 常规 的 activity 

你 启动 的 是 你 application 工 作 流 中 的 一 部 分 [Activity] (developer .android.com/reference/android/a 
pp/Activity.html1) ° 

* 43 x activity 

用 户 只 能 从 notification 中 启动， 才能 看 到 这 个 [Activity](http://developer.android.com/intl/zh-c 
n/reference/android/app/Activity.html)， 在 茶 种 意义 上 ， 这 个 [Activity](http://developer.and 
roid.com/intl/zh-cn/reference/android/app/Activity.html) 是 notification 的 扩展 ， 额 外 展示 了 一 
些 notification 本 身 难 以 展示 的 信息 。 


设置 一 个 常规 的 Activity Pendinglntent 


设置 一 个 直接 启动 的 入 口 Activity 的 Pendinglntent， 遵 循 以 下 步骤 : 


1 在 manifest 中 定义 你 application 的 Activity 层 次 ， 最 终 的 manifest 文 件 应 该 像 这 个 : 


«activity 
android:name=".MainActivity" 
android: label="@string/app_name" > 
<intent-filter> 
<action android:name="android.intent.action.MAIN" /> 
<category android:name="android.intent.category.LAUNCHER" /> 
</intent-filter> 
</activity> 
<activity 
android:name=".ResultActivity" 
android: parentActivityName=".MainActivity"> 
<meta-data 
android: name="android. support .PARENT_ACTIVITY" 
android: value=".MainActivity"/> 
</activity> 


2 在 基于 局 动 Activity 的 Intent 中 创建 一 个 返回 栈 ， 比 如 : 


int id = 1; 


Intent resultIntent - new Intent(this, ResultActivity.class); 
TaskStackBuilder stackBuilder - TaskStackBuilder.create(this); 
// Adds the back stack 
stackBuilder.addParentStack(ResultActivity.class); 
// Adds the Intent to the top of the stack 
stackBuilder.addNextIntent(resultIntent); 
// Gets a PendingIntent containing the entire back stack 
PendingIntent resultPendingIntent - 
stackBuilder.getPendingIntent(0, PendingIntent.FLAG UPDATE CURRENT); 


NotificationCompat.Builder builder - new NotificationCompat.Builder(this); 
builder.setContentIntent(resultPendingIntent); 
NotificationManager mNotificationManager - 

(NotificationManager) getSystemService(Context.NOTIFICATION SERVICE); 
mNotificationManager.notify(id, builder.build()); 


za 一 个 特定 的 Activity PendingIntent 


一 个 特定 的 Activity 不 需要 一 个 返回 栈 ， 所 以 你 不 需要 在 manifest 中 定义 Activity 的 层次 ， 以 及 
你 不 需要 调用 addParentStack()) 方 法 去 构建 一 个 返回 栈 。 作 为 代替 ， 你 需要 用 manifest 设 
置 Activity 任 务 选 项 ， 以 及 调用 getActivity()) 创 建 Pendinglntent 


1. manifest 中 ， 在 Activity 的 标签 中 增加 下 列 属 性 : android:name="activityclass" activity 的 


完整 的 类 名 。 android:taskAffinity="" 结合 你 在 代码 里 设置 的 
FLAG ACTIVITY NEW _TASK 标 识 ， 确 保 这 个 Activity 不 会 进入 application 的 默认 任务 
任何 与 application 的 默认 任务 有 密切 关系 的 任务 都 不 会 受到 影响 。 


android:excludeFromRecents="true" 将 新 任务 从 最 近 列 表 中 排除 ， 目 的 是 为 了 防止 用 户 


不 小 心 返 回 到 它 


2. 建立 以 及 发 布 notification : a. 创 建 一 个 启动 Activity 的 Intent. b. 通 过 调用 setFlags()) 方 法 并 


设置 标识 FLAG_ACTIVITY_NEW_TASK 与 FLAG_ACTIVITY_CLEAR_TASK， s 


置 Activity 在 一 个 新 的 ， 空 的 任务 中 局 动 。c. 在 Intent 中 设置 其 他 你 需要 的 选项 。 d. 通 过 调 
用 getActivity() 方 法 从 Intent 中 创建 一 个 Pendinglntent > ETURA Ponnan 当做 


setContentlntent(O) 的 参数 来 使 用 。 下 面 的 代码 片段 演示 了 这 个 过 程 : 


// Instantiate a Builder object. 
NotificationCompat.Builder builder - new NotificationCompat.Builder(this); 
// Creates an Intent for the Activity 
Intent notifyIntent - 

new Intent(new ComponentName(this, ResultActivity.class)); 
// Sets the Activity to start in a new, empty task 
notifyIntent.setFlags(Intent.FLAG ACTIVITY NEW TASK | 

Intent.FLAG ACTIVITY CLEAR TASK); 
// Creates the PendingIntent 
PendingIntent notifyIntent - 

PendingIntent.getActivity( 

this, 

9, 

notifyIntent, 

PendingIntent.FLAG UPDATE CURRENT 


) 


// Puts the PendingIntent into the notification builder 
builder.setContentIntent(notifyIntent); 
// Notifications are issued by sending them to the 
// NotificationManager system service. 
NotificationManager mNotificationManager - 
(NotificationManager) getSystemService(Context.NOTIFICATION SERVICE); 
// Builds an anonymous Notification object from the builder, and 
// passes it to the NotificationManager 
mNotificationManager.notify(id, builder.build()); 


更 新 Notification 


编写 :fastcome1985 - 原文 :http://developer.android.com/training/notify- 
user/managing.html 


当 你 需要 对 同一 事件 发 布 多 次 Notification 时 ， 你 应 该 避免 每 次 都 生成 一 个 全 新 的 Notification » 
相反 ， 你 应 该 考虑 去 更 新 先前 的 Notification ， 或 者 改变 它 的 值 ， 或 者 增加 一 些 值 ， 或 者 两 者 
同时 进行 。 


下 面 的 章节 描述 了 如 何 更 新 Notifications ， 以 及 如 何 移 除 它们 。 


改变 一 个 Notification 


想 要 设置 一 个 可 以 被 更 新 的 Notification， 需 要 在 发 布 它 的 时 候 调 

用 NotificationManagernotify(ID, notification)) 方 法 为 它 指 定 一 个 notification ID。 更 新 一 个 已 经 
发 布 的 Notification， 需 要 更 新 或 者 创建 一 个 NotificationCompat.Builder 对 象 ， 并 从 这 个 对 象 创 
建 一 个 Notification 对 象 ， 然 后 用 与 先前 一 样 的 ID 去 发 布 这 个 Notification 。 


下 面 的 代码 片段 演示 了 更 新 一 个 notification 来 反映 事件 发 生 的 次 数 ， 它 把 notification 堆 积 起 
来 ， 显 示 一 个 总 数 。 


mNotificationManager = 
(NotificationManager) getSystemService(Context.NOTIFICATION SERVICE); 
// Sets an ID for the notification, so it can be updated 
int notifyID - 1; 
mNotifyBuilder - new NotificationCompat.Builder(this) 
.setContentTitle("New Message") 
.setContentText("You've received new messages.") 
.setsmallIcon(R.drawable.ic notify status) 
numMessages - 0; 
// Start of a loop that processes data and then notifies the user 


mNotifyBuilder.setContentText(currentText) 
.setNumber (++numMessages ) ; 
// Because the ID remains unchanged, the existing notification is 
// updated. 
mNotificationManager.notify( 
notifyID, 
mNotifyBuilder.build()); 


移 除 Notification 
Notifications 将 持续 可 见 ， 除 非 下 面 任 何 一 种 情况 发 生 。 


* 用 户 清 除 Notification 单 独 地 或 者 使 用 “清除 所 有 ”( 如果 Notification 能 被 清除 ) 。 

* 你 在 创建 notification 时 调用 了 setAutoCancel(developer.android.com/reference/android/supp 
ort/v4/app/NotificationCompat .Builder.html#setAutoCancel(boolean)) 方 法 ， 以 及 用 户 点 击 了 这 个 
notification， 

* 你 为 一 个 指定 的 notification ID 调 用 了 [cancel()](developer.android.com/reference/android/ 
app/NotificationManager .html#cancel(int)) 方 法 。 这 个 方法 也 会 删除 正在 进行 的 notifications。 

* 你 调用 了 [cancelAll()](developer.android.com/reference/android/app/NotificationManager. 
html#cancelAll( ) ) 方 法 ， 它 将 会 移 除 你 先前 发 布 的 所 有 Notification。 


使 用 BigView 样 式 


编写 :fastcome1985 - 原文 :http://developer.android.com/training/notify- 
user/expanded.html 


Notificationd& Æ P $5 Notification £24 Pj ft 3L 35 BR X, > normal view (平常 的 视图 ， 下 
Fl) 5 big view (大 视图 ， 下 同 ) » Notification*? big view 样 式 只 有 当 Notification 被 扩展 时 才 
能 出 现 。 当 Notification 在 Notification 抽 层 的 最 上 方 或 者 用 户 点 击 Notification 时 才 会 展现 大 视 
图 。 


Big views 在 Android4.1 被 引进 的 ， 它 不 支持 老 版 本 设备 。 这 节 课 叫 你 如 何 让 把 big view 
notifications 合 并 进 你 的 APP， 同 时 提供 normal view 的 全 部 功能 。 更 多 信息 请 见 Notifications 
APl guide 。 


这 是 一 个 normal view 的 例子 


O Ping notification 





图 1 Normal view notification. 


这 是 一 个 big view 的 例子 


Ping notification 


(©) t forget to feed the do 





图 2 Big view notification. 


在 这 节 课 的 例子 应 用 中 ，normal view 5 big view 给 用 户 相 同 的 功能 : 


e 继续 小 睡 或 者 消除 Notification 
e 一 个 查看 用 户 设 置 的 类 似 计时 器 的 提醒 文字 的 方法 ， 


e normal view 通过 当 用 户 点 击 Notification 来 启动 一 个 新 的 activity 的 方式 提供 这 些 特性 ， 记 
住 当 你 设计 你 的 notifications 时 ， 首 先 在 normal view 中 提供 这 些 功能 ， 因 为 很 多 用 户 会 与 
notification 交 互 。 


设置 Notification 用 来 登陆 一 个 新 的 Activity 


这 个 例子 应 用 用 IntentService 的 子 类 (PingService) 来 构造 以 及 发 布 notification。 在 这 个 代 
码 片段 中 ，IntentService 中 的 方法 onHandlelntent()) 指定 了 当 用 户 点 击 notification 时 启动 一 个 
新 的 activity。 方 法 setContentlntent()) 定 义 了 pending intent 在 用 户 点 击 notification 时 被 激发 ， 
此 登陆 这 个 activity. 


Intent resultIntent = new Intent(this, ResultActivity.class); 

resultIntent.putExtra(CommonConstants.EXTRA MESSAGE, msg); 

resultIntent.setFlags(Intent.FLAG ACTIVITY NEW TASK | 
Intent.FLAG ACTIVITY CLEAR TASK); 


// Because clicking the notification launches a new ("special") activity, 
// there's no need to create an artificial back stack. 
PendingIntent resultPendingIntent - 

PendingIntent.getActivity( 

ENES, 

9, 

resultIntent, 

PendingIntent.FLAG UPDATE CURRENT 


Dm 


// This sets the pending intent that should be fired when the user clicks the 
// notification. Clicking the notification launches a new activity. 
builder.setContentIntent(resultPendingIntent); 


构造 big view 


这 个 代码 片段 展示 了 如 何在 big view 中 设置 buttons 


// Sets up the Snooze and Dismiss action buttons that will appear in the 

// big view of the notification. 

Intent dismissIntent - new Intent(this, PingService.class); 
dismissIntent.setAction(CommonConstants.ACTION DISMISS); 

PendingIntent piDismiss = PendingIntent.getService(this, 0, dismissIntent, 0); 


Intent snoozeIntent = new Intent(this, PingService.class); 
snoozeIntent.setAction(CommonConstants.ACTION SNOOZE); 
PendingIntent piSnooze = PendingIntent.getService(this, 0, snoozeIntent, 0); 


这 个 代码 片段 展示 了 如 何 构 造 一 个 Builder 对 象 ， 它 设置 了 big view 的 样式 为 "big text", 同 时 设 
置 了 它 的 内 容 为 提醒 文字 。 它 使 用 addAction()) 方 法 来 添加 将 要 在 big view 中 出 现 的 Snooze 与 
Dismiss 按 钮 (以 及 它们 相关 联 的 pending intents). 


// Constructs the Builder object. 

NotificationCompat.Builder builder - 
new NotificationCompat.Builder(this) 
.setsmallIcon(R.drawable.ic stat notification) 
.setContentTitle(getString(R.string.notification)) 
.setContentText(getString(R.string.ping)) 
.setDefaults(Notification.DEFAULT ALL) // requires VIBRATE permission 
/* 
* 


Sets the big view "big text" style and supplies the 


* 


text (the user's reminder message) that will be displayed 


* 


in the detail area of the expanded notification. 

* These calls are ignored by the support library for 

* pre-4.1 devices. 

a 

.setStyle(new NotificationCompat.BigTextStyle() 
.bigText(msg)) 

.addAction (R.drawable.ic_stat_dismiss, 
getString(R.string.dismiss), piDismiss) 

.addAction (R.drawable.ic_stat_snooze, 

getString(R.string.snooze), piSnooze); 


显示 Notification 进 度 


编写 :fastcome1985 - 原文 :http://developer.android.com/training/notify-user/display- 
progress.html 


Notifications 可 以 包含 一 个 展示 用 户 正 在 进行 的 操作 状态 的 动画 进度 指示 器 。 如 果 你 可 以 在 任 
何 时 候 估算 这 个 操作 得 花 多 少时 间 以 及 当前 已 经 完成 多 少 ， ik vA “determinate (确定 的 ， 
下 同 ) "形式 的 指示 器 (一 个 进度 条 ) 。 如 果 你 不 能 估算 这 个 操作 的 长 度 ， 使 

A| “indeterminate (RAR , TR) "形式 的 指示 器 (一 个 活动 的 指示 器 ) © 


进度 指示 器 用 ProgressBar 平 台 实 现 类 来 显示 。 


使 用 进度 指示 器 ， 可 以 调用 setProgress() 方 法 。determinate 4 indeterminate 形 式 将 在 下 面 


展示 国定 长 度 的 进度 指示 器 


为 了 展示 一 个 确定 长 度 的 进度 条 ， 调 用 setProgress(max, progress, ee ees 度 条 添加 
进 notification， 然 后 发 布 这 个 notification， 第 三 个 参数 是 个 boolean 类 型 ， 决 定 进度 条 是 

indeterminate (true) 还 是 determinate (false)。 在 你 操作 进行 时 ， 增 加 progress， 更 新 

notification。 在 操作 结束 时 ，progress 应 该 等 于 max。 BA 的 调用 setProgress()) 的 方法 


是 设置 max 为 100， 然 后 增加 progress 就 像 操作 的 "完成 百分比 "。 


当 操 作 完 成 的 时 候 ， 你 可 以 选择 或 者 让 进度 条 继续 展示 ， 或 者 移 除 它 。 无 论 哪 种 情况 下 ， 记 
得 更 新 notification 的 文字 来 显示 操作 完成 。 移 除 进 度 条 ， een 0, false)) 方 法 . 比 
如 : 


aque ato] = ap 


mNotifyManager = 
(NotificationManager) getSystemService(Context.NOTIFICATION SERVICE); 
mBuilder - new NotificationCompat.Builder(this); 
mBuilder.setContentTitle("Picture Download") 
.setContentText("Download in progress") 
.setSmallIcon(R.drawable.ic notification); 
// Start a lengthy operation in a background 
new Thread( 
new Runnable() { 
@Override 
public void run() { 
int incr; 


J? VO ENe VengeEeny Operation 20 times 


for (incr = 0; incr <= 100; incrt+=5) { 





// Sets the progress tc 
rren pletio nC t 
mBuilder.setProgress(100, incr, false); 
// Displays the progress bar for the first t 
mNotifyManager.notify(id, mBuilder.build()); 
// Sleeps the thread, simulating an operation 


Thread.sleep(5*1000); 
) catch (InterruptedException e) { 
Log.d(TAG, "sleep failure"); 


j 


han ho AINT ic Cs at en Ara > thce pe Ne See ee eae ae 
nen Enel roop rS fanwtsned, Updates tie mo Lucarnon 


mBuilder.setContentText("Download complete") 


e Progress par 





.setProgress(0,0, false); 
mNotifyManager.notify(id, mBuilder.build()); 


} 


» Lhe thread Dy Cal- g tne runi j etnod l s RUNNADLE 


a 


结果 notifications 显 示 在 图 1 中 ， 左 边 是 操作 正在 进行 中 的 notification 的 快照 ， 右 边 是 操作 已 经 
完成 的 notification 的 快照 。 


8:44 en 


Picture Download 


n Picture Do 
Ed 





图 1 操作 正在 进行 
中 与 完成 时 的 进度 条 


展示 持续 的 活动 的 指示 器 


为 了 展示 一 个 持续 的 (indeterminate) 活 动 的 指示 器 ,用 setProgress(0, 0, true)) 方 法 把 指示 il 
Je 3t notification > bles nee 。 前 两 个 参数 忽略 ， 第 三 个 参数 决定 indicator 还 
indeterminate。 结 果 是 指示 条 有 同样 的 样式 ， 除 了 它 的 动画 正在 进行 。 


在 操作 开始 的 时 候 发 布 notification， 动 画 将 会 一 直 进 行 直到 你 更 新 notification。 当 操作 完成 

时 ， 调 用 setProgress(0, 0, false)) 方法 ， 然 后 更 新 notification 来 移 除 这 个 动画 指示 器 。 一 定 
要 这 么 做 ， 否 责 即 使 你 操作 完成 了 ， 动 画 还 是 会 在 那 运 行 。 同 时 也 要 记得 更 新 notification 的 文 
字 来 显示 操作 完成 。 


观察 持续 的 活动 的 指示 器 是 如 何 工作 的 ， 看 前 面 的 代码 。 定 位 到 下 面 的 几 行 


to a max value, the current completion 





percent 


aae 
Lage, 


"determinate" state 
NEU Eden S cp cereee( tee incr, false); 
// Issues the notification 


mNotifyManager.notify(id, mBuilder.build()); 


和 你 找到 的 代码 用 下 面 的 几 行 代码 代替 ， 注 意 setProgress() 方 法 的 第 三 个 参数 设置 成 了 true， 
e 进度 条 是 indeterminate 3 # 55 o 


// Sets an activity indicator for an operation of indeterminate length 
mBuilder. mm OF erue), 
// Issues the notification 


mNotifyManager.notify(id, mBuilder.build()); 


Picture Download 





图 2 正在 进行 的 活动 的 指示 器 


增加 搜索 功能 


编写 :Lin-H - /$ x-:http://developer.android.com/training/search/index.html 


Android 的 内 置 搜索 功能 ， 能 够 在 app 中 方便 地 为 所 有 用 户 提供 一 个 统一 的 搜索 体验 。 根 据 设 
备 所 运行 的 Android 版 本 ， 有 两 种 方式 可 以 在 你 的 app 中 实现 搜索 。 本 节 课 程 涵盖 如 何 像 
Android 3.0 中 介绍 的 那样 用 SearchView 添 加 搜索 ， 使 用 系统 提供 的 默认 搜索 框 来 向 下 兼容 旧 
版 本 Android 。 


Lessons 


e 建立 搜索 界面 

学 习 如 何 向 你 的 app 中 添加 搜索 界面 ， 如 何 设置 activity 去 处 理 搜索 请 求 
e 保存 并 搜索 数据 

学 习 在 SQLite 虚 拟 数 据 库 表 中 用 简单 的 方法 储存 和 搜索 数据 
e 保持 向 下 兼容 

通过 使 用 搜索 功能 来 学 习 如 何 向 下 兼容 旧版 本 设备 


建立 搜索 界面 


编写 :Lin-H - 原文 :http:/developerandroid.comytraining/search/setup.html 


从 Android 3.0 开 始 ， 在 action bar 中 使 用 SearchView 作 为 iiem， 是 在 你 的 app 中 提供 搜索 的 一 

种 更 好 方法 。 像 其 他 所 有 在 action bar 中 的 item 一 样 ， 你 可 以 定义 SearchView 在 有 足够 空间 的 
时 候 总 是 显示 ， 或 设置 为 一 个 折 有 操作 (collapsible action), 一 开始 SearchView 作 为 一 个 图 标 显 
示 ， 当 用 户 点 击 图 标 时 再 显示 搜索 框 占据 整个 action bar 


Note: 在 本 课程 的 后 面 ， 你 会 学 习 对 那些 不 支持 SearchView 的 设备 ， 如 何 使 你 的 app 向 下 
兼容 至 Android 2.1(APllevel7) 版 本 。 


添加 Search View 到 action bar 中 


为 了 在 action bar 中 添加 SearchView， 在 你 的 工程 目录 res/menu/ 中 创建 一 个 名 

为 options menu.xml 的 文件 ， 再 把 下 列 代码 添加 到 文件 中 。 这 段 代码 定义 了 如 何 创 建 search 
item ， 比 如 使 用 的 图 标 和 item 的 标题 。 collapseActionview 属性 允许 你 的 SearchView 占 据 整 
个 action bar， 在 不 使 用 的 时 候 折 醒 成 普通 的 action bar item。 由 于 在 手持 设备 中 action bar 的 
空间 有 限 ， 建 议 使 用 collapsibleActionview 属性 来 提供 更 好 的 用 户 体验 。 


«?xml version="1.0" encoding="utf-8"?> 
<menu xmlns:android="http://schemas.android.com/apk/res/android"> 
<item android:id="@+id/search" 

android:title="@string/search title" 
android:icon="@drawable/ic_search" 
android:showAsAction="collapseActionView|ifRoom" 
android:actionViewClass-"android.widget.SearchView" /> 

</menu> 


Note: 如 果 你 的 menu items 已 经 有 一 个 XML 文件 ， 你 可 以 只 把 «item» 元 素 添加 入 文件 。 


要 在 action bar 中 显示 SearchView， 在 你 的 activity 中 onCreateOptionsMenu()) 方 法 内 填充 XML 


菜单 资源 ( res/menu/options menu.xml ): 


@Override 

public boolean onCreateOptionsMenu(Menu menu) { 
MenuInflater inflater - getMenuInflater(); 
inflater.inflate(R.menu.options menu, menu); 


retur t mue 


如 果 你 立即 运行 你 的 app，SearchView 就 会 显示 在 你 app 的 action bar 中 ， 但 还 无 法 使 用 。 你 
现在 需要 定义 SearchView 如 何 运 行 。 


创建 一 个 检索 配置 


检索 配置 (searchable configuration) 在 res/xml/searchable.xml 文件 中 定义 了 SearchView 如 何 
运行 。 检 索 配 置 中 至 少 要 包含 一 个 android:label 属性 ， 与 Android manifest 中 

的 «application» 或 «activity» android:label 属性 值 相 同 。 但 我 们 还 是 建议 添 

加 android:hint 属性 来 告诉 用 户 应 该 在 搜索 框 中 输入 什么 内 容 : 


«?xml version="1.0" encoding="utf-8"?> 
«searchable xmlns:android-"http://schemas.android.com/apk/res/android" 


android: label="@string/app_name" 
android:hint="@string/search_hint" /> 


在 你 的 应 用 的 manifest 文 件 中 ， 声 明 一 个 指向 res/xml/searchable.xml 文件 的 <meta-data> 元 
素 ， 来 告诉 你 的 应 用 在 哪里 能 找到 检索 配置 。 在 你 想 要 显示 SearchView 的 «activity» Y Ë 
明 <meta-data> 元 素 : 


<ACEIVIEY se 


<meta-data android:name="android.app.searchable" 
android: resource="@xml/searchable" /> 


</activity> 


在 你 之 前 创建 的 onCreateOptionsMenu()) 方 法 中 ， 调 用 setSearchablelnfo(Searchablelnfo)) 把 
SearchView 和 检索 配置 关联 在 一 起 : 


@Override 

public boolean onCreateOptionsMenu(Menu menu) { 
MenuInflater inflater - getMenuInflater(); 
inflater.inflate(R.menu.options menu, menu); 


// 关联 检索 配置 和 SearchView 
SearchManager searchManager = 
(SearchManager) getSystemService(Context.SEARCH SERVICE); 
SearchView searchView - 
(SearchView) menu.findItem(R.id.search).getActionView(); 
searchView.setSearchableInfo( 
searchManager.getSearchableInfo(getComponentName())); 


return true; 


调用 getSearchablelnfo()) 返 回 一 个 Searchablelnfo 由 检索 配置 XML 文件 创建 的 对 象 。 检 索 配 置 
与 SearchView 正 确 关 联 后 ， 当 用 户 提 交 一 个 搜索 请 求 时 ，SearchView 会 以 

ACTION. SEARCH intent 启 动 一 个 activity。 所 以 你 现在 需要 一 个 能 过 滤 这 个 intent 和 处 理 搜索 
请 求 的 activity 。 


创建 一 个 检索 activity 


当 用 户 提交 一 个 搜索 请 求 时 ，SearchView 会 尝试 以 ACTION _SEARCH 启 动 一 个 activity。 检 索 
activity 会 过 滤 ACTION_SEARCH intent 并 在 某 种 数据 集中 根据 请 求 进行 搜索 。 要 创建 一 个 检 
索 activity， 在 你 选择 的 activity 中 声明 对 ACTION_SEARCH intent 过 滤 : 


«activity android:name-".SearchResultsActivity" ... » 


«intent-filter» 
«action android:name="android.intent.action.SEARCH" /> 
</intent-filter> 


</activity> 


在 你 的 检索 activity 中 ， 通 过 在 onCreate()) 方 法 中 检查 ACTION_SEARCH intent 来 处 理 它 。 


Note: 如 果 你 的 检索 activity 在 single top mode 下 启动 ( android:launchMode-"singleTop" ) > 
也 要 在 onNewlntent()) 方 法 中 处 理 ACTION_SEARCH intent。 在 single top mode 下 你 的 
activity 只 有 一 个 会 被 创建 ， 而 随后 启动 的 activity 将 不 会 在 栈 中 创建 新 的 activity。 这 种 户 
动 模式 很 有 用 ， 因 为 用 户 可 以 在 当前 activity 中 进行 搜索 ， 而 不 用 在 每 次 搜索 时 都 创建 一 
个 activity 实 例 。 


public class SearchResultsActivity extends Activity ( 


@Override 
public void onCreate(Bundle savedInstanceState) { 


handleIntent(getIntent()); 
@Override 
protected void onNewIntent(Intent intent) { 


handleIntent(intent); 


private void handleIntent(Intent intent) { 


if (Intent.ACTION SEARCH.equals(intent.getAction())) { 
String query - intent.getStringExtra(SearchManager . QUERY) ; 
// 通 过 某 种 方法 ， 根 据 请 求 检 索 你 的 数据 


如 果 你 现在 运行 你 的 app，SearchView 就 能 接收 用 户 的 搜索 请 求 ， 以 ACTION_SEARCH 
intent 启 动 你 的 检索 activity。 现 在 就 由 你 来 解决 如 何 依据 请 求 来 储存 和 搜索 数据 。 


保存 并 搜索 数据 


编写 :Lin-H - 原文 :http://developer.android.com/training/search/search.html 


有 很 多 方法 可 以 储存 你 的 数据 ， 比 如 储存 在 线 上 的 数据 库 ， 本 地 的 SQLite 数 据 库 ， 甚 至 是 文 
本 文件 。 你 自己 来 选择 最 适合 你 应 用 的 存储 方式 。 本 节 课 程 会 向 你 展示 如 何 创 建 一 个 健壮 的 
可 以 提供 全 文 搜索 的 SQLite 虚 拟 表 。 并 从 一 个 每 行 有 一 组 单词 -解释 对 的 文件 中 将 数据 填 入 。 


创建 虚拟 表 


虚拟 表 与 SQLite 表 的 运行 方式 类 似 ， 但 虚拟 表 是 通过 回调 来 向 内 存 中 的 对 象 进行 读 取 和 和 写 
入 ， 而 不 是 通过 数据 库 文件 。 要 创建 一 个 虚拟 表 ， 首 先 为 该 表 创 建 一 个 类 : 


public class DatabaseTable { 
private final DatabaseOpenHelper mDatabaseOpenHelper; 


public DatabaseTable(Context context) { 
mDatabaseOpenHelper - new DatabaseOpenHelper(context); 


} 


在 DatabaseTable 类 中 创建 一 个 继承 SQLiteOpenHelper 的 内 部 类 。 你 必须 重 写 
类 SQLiteOpenHelper 中 定义 的 abstract 方 法 ， 才 能 在 必要 的 时 候 创 建 和 更 新 你 的 数据 库 表 。 
例如 ， 下 面 一 段 代 码 声明 了 一 个 数据 库 表 ， 用 来 储存 字典 app 所 需 的 单词 。 


public class DatabaseTable { 


private static final String TAG - "DictionaryDatabase"; 


/7 字典 的 表 中 将 要 包含 的 列 项 
public static final String COL WORD = "WORD"; 
public static final String COL DEFINITION - "DEFINITION"; 


private static final String DATABASE NAME - "DICTIONARY"; 
private static final String FTS VIRTUAL TABLE - "FTS"; 
private static final int DATABASE VERSION - 1; 


private final DatabaseOpenHelper mDatabaseOpenHelper; 


public DatabaseTable(Context context) { 
mDatabaseOpenHelper - new DatabaseOpenHelper(context); 


private static class DatabaseOpenHelper extends SQLiteOpenHelper { 


private final Context mHelperContext; 
private SQLiteDatabase mDatabase; 


private static final String FTS TABLE CREATE - 
"CREATE VIRTUAL TABLE ”+ FTS VIRTUAL TABLE + 
“PUSING ECSS (s 
COL WORD + ", "+ 
COL DEFINITION + ")"; 


DatabaseOpenHelper(Context context) { 
super(context, DATABASE NAME, null, DATABASE VERSION); 
mHelperContext - context; 


@Override 

public void onCreate(SQLiteDatabase db) { 
mDatabase = db; 
mDatabase.execSQL(FTS TABLE CREATE); 


@Override 
public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { 
Log.w(TAG, "Upgrading database from version " + oldVersion + " to " 
+ newVersion + ", which will destroy all old data"); 
db.execSQL("DROP TABLE IF EXISTS " + FTS VIRTUAL TABLE); 
onCreate(db) ; 


HATE Dh RR 


现在 ， 表 需要 数据 来 储存 。 下 面 的 代码 会 向 你 展示 如 何 读 取 一 个 内 容 为 单词 和 解释 的 文本 文 
件 (位 于 res/raw/definitions.txt )， 如 何 解析 文件 与 如 何 将 文件 中 的 数据 按 行 插入 虚拟 表 中 。 
为 防止 UI 锁 死 这 些 操作 会 在 另 一 条 线程 中 执行 。 将 下 面 的 一 段 代码 添加 到 你 

的 DatabaseOpenHelper 内 部 类 中 。 


Tip: 你 也 可 以 设置 一 个 回调 来 通知 你 的 Ul activity 线 程 的 完成 结果 。 


private void loadDictionary() { 
new Thread(new Runnable() { 
public void run() { 
try { 
loadwords(); 
} catch (IOException e) { 
throw new RuntimeException(e); 


} 
}).start(); 


private void loadWords() throws IOException { 
final Resources resources = mHelperContext.getResources(); 
InputStream inputStream = resources. openRawResource(R.raw.definitions); 
BufferedReader reader = new BufferedReader(new InputStreamReader (inputStream) ); 


try { 
String line; 
while ((line = reader.readLine()) != null) { 
String[] strings = TextUtils.split(line, "-"); 
if (strings.length < 2) continue; 
long id = addWord(strings[0].trim(), strings[1].trim()); 
if (id < 0) { 
Log.e(TAG, "unable to add word: " + strings[0].trim()); 
j 
} 
} finally ( 


reader.close(); 


public long addword(String word, String definition) { 
ContentValues initialValues - new ContentValues(); 
initialValues.put(COL WORD, word); 
initialValues.put(COL DEFINITION, definition); 


return mDatabase.insert(FTS VIRTUAL TABLE, null, initialValues); 


任何 恰当 的 地 方 ， 都 可 以 调用 loadpictionary() 方法 向 表 中 卉 入 数据 。 一 个 比较 好 的 地 方 
是 DatabaseopenHelper 类 的 onCreate()) 方 法 中 ， 紧 随 创建 表 之 后 : 


@Override 


public void onCreate(SQLiteDatabase db) { 
mDatabase - db; 


mDatabase.execSQL(FTS TABLE CREATE); 
loadDictionary(); 


搜索 请 求 


当 你 的 虚拟 表 创 建 好 并 填 入 数据 后 ， 根 据 SearchView 提 供 的 请 求 搜索 数据 。 将 下 面 的 方法 添 
加 到 DatabaseTable 类 中 ， 用 来 创建 搜索 请 求 的 SQL 语 句 : 


public Cursor getwordMatches(String query, String[] columns) { 
String selection = COL WORD + " MATCH ?"; 
String[] selectionArgs = new String[] {query+'"*"}; 


return query(selection, selectionArgs, columns); 


private Cursor query(String selection, String[] selectionArgs, String[] columns) { 
SQLiteQueryBuilder builder - new SQLiteQueryBuilder(); 
builder.setTables(FTS VIRTUAL TABLE); 


Cursor cursor - builder.query(mDatabaseOpenHelper.getReadableDatabase(), 
columns, selection, selectionArgs, null, null, null); 


if (cursor == null) { 
return null; 

} else if (!cursor.moveToFirst()) { 
cursor.close(); 
return null; 


} 


return cursor; 


调用 getwordMatches() 来 搜索 请 求 。 任 何 符 合 的 结果 返回 到 Cursor 中 ， 可 以 直接 遍历 或 是 建 
立 一 个 ListView。 这 个 例子 是 在 检索 activity 的 handletntent() 方法 中 调 

用 getwordMatches() 。 请 记 住 ， 因 为 之 前 创建 的 intent filter > 4 A activity 

在 ACTION_SEARCH intent 中 额外 接收 请 求 作 为 变量 存储 : 


DatabaseTable db = new DatabaseTable(this); 


private void handleIntent(Intent intent) { 


if (Intent.ACTION_SEARCH.equals(intent.getAction())) { 
String query = intent.getStringExtra(SearchManager . QUERY) ; 
Cursor c - db.getWordMatches(query, null); 
// 执 行 Cursor 并 显示 结果 


保持 向 下 兼容 


编写 :Lin-H - /$ X:http://developer.android.com/training/search/backward-compat.html 


SearchView 和 action bar 只 在 Android 3.0 以 及 以 上 版 本 可 用 。 为 了 支持 旧版 本 平台 ， 你 可 以 回 
到 搜索 对 话 框 。 搜 索 框 是 系统 提供 的 UI， 在 调用 时 会 履 盖 在 你 的 应 用 的 最 顶端 。 


设置 最 小 和 目标 API 级 别 


要 设置 搜索 对 话 框 ， 首 先 在 你 的 manifest 中 声明 你 要 支持 旧版 本 设备 ， 并 且 目 标 平台 为 
Android 3.0 或 更 新 版 本 。 当 你 这 么 做 之 后 ， 你 的 应 用 会 自动 地 在 Android 3.0 或 以 上 使 用 action 
bar， 在 旧版 本 的 设备 使 用 传统 的 目录 系统 :: 


«uses-sdk android:minSdkVersion="7" android:targetSdkVersion-z"15" /> 


«application» 


为 旧版 本 设备 提供 搜索 对 话 杠 


要 在 旧版 本 设备 中 调用 搜索 对 话 框 ， 可 以 在 任何 时 候 ， 当 用 户 从 选项 目录 中 选择 搜索 项 时 ， 
调用 onSearchRequested())。 因 为 Android 3.0 或 以 上 会 在 action bar 中 显示 SearchView( 就 像 
在 第 一 节 课 中 演示 的 那样 )， 所 以 当 用 户 选 择 目 录 的 搜索 项 时 ， 只 有 Android 3.0 以 下 版 本 的 会 
调用 onOptionsltemSelected())。 


@Override 
public boolean onOptionsItemSelected(MenuItem item) { 
switch (item.getItemId()) { 
case R.id.search: 
onSearchRequested(); 
return true; 
default: 
return false; 


we 
we 


在 运行 时 检查 Android 的 构建 版 本 


在 运行 时 ， 检 查 设 备 的 版 本 可 以 保证 在 旧版 本 设备 中 ， 不 使 用 不 支持 的 SearchView。 在 我 们 
这 个 例子 中 ， 这 一 操作 在 onCreateOptionsMenu()) 方 法 中 : 


@Override 
public boolean onCreateOptionsMenu(Menu menu) { 


MenuInflater inflater - getMenuInflater(); 
inflater.inflate(R.menu.options menu, menu); 


if (Build.VERSION.SDK INT >= Build.VERSION CODES.HONEYCOMB) { 

SearchManager searchManager - 

(SearchManager) getSystemService(Context.SEARCH SERVICE); 
SearchView searchView - 

(SearchView) menu.findItem(R.id.search).getActionView(); 
searchView. setSearchableInfo( 

searchManager .getSearchableInfo(getComponentName())); 
searchView.setIconifiedByDefault(false); 


} 


return true; 


使 得 你 的 App 内 容 可 被 Google 搜 索 


编写 :Lin-H - /$ x-:http://developer.android.com/training/app-indexing/index.html 


随 着 移动 app 变 得 越 来 越 普 遍 ， 用 户 不 仅仅 从 网 站 上 查找 相关 信息 ， 也 在 他 们 安装 的 app 上 查 
找 。 你 可 以 使 Google 能 够 抓 取 你 的 app 内 容 ， 当 内 容 与 你 自己 的 网 页 一 致 时 ，Google 搜 索 的 
结果 会 将 你 的 app 作 为 结果 展示 给 用 户 。 


通过 为 你 的 activity 提 供 intent filter， 可 以 使 Google 搜 索 展 示 你 的 app 中 特定 的 内 容 。Google 搜 
索 应 用 索引 (Google Search app indexing) 通 过 在 用 户 搜索 结果 的 网 页 链接 这 附 上 相关 的 app 
内 容 链 接 ， 补 充 了 这 一 功能 。 使 用 移动 设备 的 用 户 可 以 在 他 们 的 搜索 结果 中 点 击 链接 来 打开 
你 的 app， 使 他 们 能 够 直接 浏览 你 的 app 中 的 内 容 ， 而 不 需要 打开 网 页 。 


要 局 用 Google 搜 索 应 用 索引 ， 你 需要 把 有 关 app 与 网 页 之 间 联 系 的 信息 提供 给 Google。 这 个 
过 程 包括 下 面 几 个 步骤 : 


1. 通过 在 你 的 app manifest 中 添加 intent filter 来 开启 链接 到 你 的 app 中 指定 内 容 的 深度 链 
接 。 


2， 在 你 的 网 站 中 的 相关 页 面 或 Sitemap 文 件 中 为 这 些 链接 添加 注解 。 


3. 24 AFAR * (Googlebot) Google Play store 中 通过 APK 抓 取 ， 建 立 app 内 容 索 引 。 
在 早期 采用 者 计划 (early adopter program) 中 作为 参与 者 加 入 时 ， 会 自动 选择 允许 。 


这 节 课 程 ， 会 向 你 展示 如 何 启 用 深度 链接 和 建立 应 用 内 容 索 引 ， 使 用 户 可 以 从 移动 设备 搜索 
结果 直接 打开 此 内 容 。 


Lessons 


e 为 App 内 容 开 启 深度 链接 
演示 如 何 添加 intent filter 来 启用 链接 app 内 容 的 深度 链接 
e 为 索引 指定 App 内 容 


演示 如 何 给 网 站 的 metadata 添 加 注解 ， 使 Google 的 算法 能 为 app 内 容 建 立 索引 


为 App 内 容 开 尼 深 度 链接 


编写 :Lin-H - /$ xc:http://developer.android.com/training/app-indexing/deep-linking.html 


为 使 Google 能 够 抓 取 你 的 app 内 容 ， 并 人 允许 用 户 从 搜索 结果 进入 你 的 app， 你 必须 给 你 的 app 
manifest 中 相关 的 activity 添 加 intent filter。 这 些 intent filter 能 使 深度 链接 与 你 的 任何 activity 相 
连 。 例 如 ， 用 户 可 以 在 购物 app 中 ， 点 击 一 条 深度 链接 来 浏览 一 个 介绍 了 自己 所 搜索 的 产品 的 
页 面 。 


为 你 的 深度 链接 添加 Intent filter 


要 创建 一 条 与 你 的 app 内 容 相 连 的 深度 链接 ， 添 加 一 个 包含 了 以 下 这 些 元 素 和 属性 值 的 intent 
filter 到 你 的 manifest 中 : 


<action> 


指定 ACTION_VIEW 的 操作 ， 使 得 Google 搜 索 可 以 触及 intent filter ° 


<data> 
添加 一 个 或 多 个 «data» 标签 ， 每 一 个 标签 代表 一 种 activity 对 URI 格 式 的 解析 ， <data> 必须 


一 个 
至 少 包 含 android:scheme 属 性 。 
你 可 以 添加 额外 的 属性 来 改善 activity 所 接受 的 URI 类 型 。 例 如 ， 你 或 许 有 几 个 activity 可 以 接受 
相似 的 URI， 它 们 仅仅 是 路 径 名 不 同 。 在 这 种 情况 下 ， 使 用 android:path 属 性 或 它 的 变形 
( pathPattern 或 pathprefix )， 使 系统 能 辨别 对 不 同 的 URI 路 径 应 该 启动 哪个 activity。 


«category» 


包括 BROWSABLE category ° BROWSABLE category 1 T /& intent filter 能 被 浏览 器 访问 是 必 
— 。 没 有 这 个 category， 在 浏览 器 中 点 击 链接 无 法 解析 到 你 的 app。DEFAULT category 

选 的 ， 但 建议 添加 。 没 有 这 个 category，activity 只 能 够 使 用 app 组 件 名 称 以 显示 
S. 动 。 


下 面 的 一 段 XML 代码 向 你 展示 ， 你 应 该 如 何在 manifest 中 为 深度 链接 指定 一 个 intent filter ° 
URI “example://gizmos” 和 “http://www.example.com/gizmos” 都 能 够 解析 到 这 个 activity ° 


«activity 
android:name="com.example.android.GizmosActivity" 
android: label="@string/title_gizmos" > 
<intent-filter android: label="@string/filter_title_viewgizmos"> 
«action android:name-"android.intent.action.VIEW" /> 
«category android:name-"android.intent.category.DEFAULT" /» 
«category android:name-"android.intent.category.BROWSABLE" /» 
<!-- 接受 以 "example://gizmos” 开 头 的 URIS  --» 
«data android:scheme="example" 
android:host="gizmos" /> 
<!-- 接受 以 "http://www.example.com/gizmos” 开 头 的 URIS  --» 
<data android:scheme="http" 
android:host="www.example.com" 
android:pathPrefix-"gizmos" /» 
</intent-filter> 
</activity> 


3 fy de 6,72 7] 48 X activity A X 9 URIK intent filter 添 加 到 你 的 app manifest 后 ，Android 就 可 以 
在 你 的 app 运 行 时 ， 为 app 与 匹配 URI 的 Intent 建 立 路 径 。 


Note: 对 一 个 URI pattern > intent filter 可 以 只 包含 一 个 单一 的 data 元 素 ， 创 建 不 同 的 
intent filter 来 匹配 额外 的 URI pattern ° 


学 习 更 多 关于 定义 intent filter， 见 Allow Other Apps to Start Your Activity 


从 传 入 的 intent 读 取 数 据 


一 旦 系统 通过 一 个 intent filter 启 动 你 的 activity， 你 可 以 使 用 由 Intent 提 供 的 数据 来 决定 需要 处 
理 什么 。 调 用 getData()) 和 getAction()) 方 法 来 取出 传 入 Intent 中 的 数据 与 操作 。 你 可 以 在 
activity 生 命 周 期 的 任何 时 候 调用 这 些 方法 ， 但 一 般 情 况 下 你 应 该 在 前 期 回调 如 onCreate()) 
或 onStart()) 中 调用 。 


这 个 是 一 段 代 码 ， 展 示 如 何 从 Intent 中 取出 数据 : 


@Override 

public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState) ; 
setContentView(R.layout.main); 


Intent intent - getIntent(); 


String action - intent.getAction(); 
Uri data - intent.getData(); 


遵守 下 面 这 些 惯例 来 提高 用 户 体 验 : 


e 深度 链接 应 直接 为 用 户 打 开 内 容 ， 不 需要 任何 提示 ， 插 播 式 广告 页 和 登录 页 面 。 要 确保 
用 户 能 看 到 app 的 内 容 ， 即 使 之 前 从 没 打 开 过 这 个 应 用 。 当 用 户 从 启动 器 打开 app 时 ， 可 
以 在 操作 结束 后 给 出 提示 。 这 个 准则 也 同样 适用 于 网 站 的 first click free 体 验 。 

e 遵循 Navigation with Back and Up 中 的 设计 指导 ， 来 使 你 的 app 能 够 满足 用 户 通过 深度 链 
接 进 入 app 后 ， 向 后 导航 的 需求 。 


om) 人 下 SE 应 LR l3 

测试 你 的 深度 链接 

你 可 以 使 用 Android Debug Bridge 和 activity 管 理 (am) 工 具 来 测试 你 指定 的 intent filter URI， 能 
否 正 确 解析 到 正确 的 app activity。 你 可 以 在 设备 或 者 模拟 器 上 运行 adb 命 令 。 


测试 intent filter URI 的 一 般 adb 语 法 是 : 
$ adb shell am start 


-W -a android.intent.action.VIEW 
-d <URI> <PACKAGE> 


例如 ， 下 面 的 命令 试图 浏览 与 指定 URI 相 关 的 目标 app activity ° 


$ adb shell am start 
-W -a android.intent.action.VIEW 
-d "example://gizmos" com.example.android 


` ou 人 

为 索引 指定 App 内 容 
编写 :Lin-H - 原文 : http://developer.android.com/training/app-indexing/enabling-app- 
indexing.html 


Google 的 网 页 候 虫 机 器 (Googlebot) 会 抓 取 页 面 ， 并 为 Google 搜 索引 擎 建立 索引 ， 也 能 为 你 的 
Android app 内 容 建 立 索引 。 通 过 选择 加 入 这 一 功能 ， 你 可 以 允许 Googlebot 通 过 抓 取 在 
Google Play Store 中 的 APK 内 容 ， 为 你 的 app 内 容 建 立 索 引 。 要 指出 哪些 app 内 容 你 想 被 
Google 索 引 ， 只 需要 添加 链接 元 素 到 现 有 的 Sitemap 文 件 ， 或 添加 到 你 的 网 站 中 每 个 页 面 

的 «head» 元 素 中 ， 以 相同 的 方式 为 你 的 页 面 添加 。 


你 所 共享 给 Google 搜 索 的 深度 链接 必须 按照 下 面 的 URI 格 式 : 


android-app://<package_name>/<scheme>/<host_path> 


构成 URI 的 各 部 分 是 : 
e package name 代表 在 Google Play Developer Console 中 所 列 出 来 的 你 的 APK 的 包 名 。 
e scheme 匹配 你 的 intent filter 的 URI 方 案 。 
。 host path 找 出 你 的 应 用 中 所 指定 的 内 容 。 


下 面 的 几 节 令 述 如 何 添加 一 个 深度 链接 URI 到 你 的 Sitemap 或 网 页 中 。 


添加 深度 链接 (Deep link) 到 你 的 Sitemap 
要 在 你 的 Sitemap 中 为 Google 搜 索 app 索 引 (Google Search app indexing) 添 加 深度 链接 的 注 
解 ， 使 用 <xhtml:link> 标签 ， 并 指定 用 作 替 代 URI 的 深度 链接 。 


例如 ， 下 面 一 段 XML 代码 向 你 展示 如 何 使 用 <loc> 标签 指定 一 个 链接 到 你 的 页 面 的 链接 ， 以 
及 如 何 使 用 <xhtml:link> 标签 指定 链接 到 你 的 Android app 的 深度 链接 。 


<?xml version="1.0" encoding-" UTF-8" ?> 
<urlset 
xmlns-"http://www.sitemaps.org/schemas/sitemap/0.9" 
xmlins:xhtml-"http://www.w3.0rg/1999/xhtml"» 
«url» 
<loc>example://gizmos</loc> 
<xhtml: link 
rel="alternate" 
href="android-app://com.example.android/example/gizmos" /> 


</url> 


</urlset> 


添加 深度 链接 到 你 的 网 页 中 


除了 在 你 的 Sitemap 文 件 中 ， 为 Google 搜 索 app 索 引 指 定 深 度 链 接 外 ， 你 还 可 以 在 你 的 HTML 
ae 页 中 给 深度 链接 添加 注解 。 你 可 以 在 «head 标签 内 这 么 做 ， 为 每 一 个 页 面 添加 一 
个 «linke 标签 ， 并 指定 用 作 替 代 URI 的 深度 链接 。 


例如 ， 下 面 的 一 段 HTML 代 码 向 你 展示 如 何在 页 面 中 指定 一 个 URL 为 example://gizmos 的 相应 
的 深度 链接 。 


«html» 
«head» 
«link rel="alternate" 
href="android-app://com.example.android/example/gizmos" /> 


</head> 
<body> ... </body> 


允许 Google 通 过 你 的 app 抓 取 URL 请 求 


一 般 来 说 ， 你 可 以 通过 使 用 robots txt 文件 ， 来 控制 Googlebot 如 何 抓 取 你 网 站 上 的 公开 访问 的 
URL。 当 Googlebot 为 你 的 app 内 容 建立 索引 后 ， 你 的 app 可 以 把 HTTP 请 求 当做 一 般 操作 。 但 
是 ， 这 些 请 求 会 被 视 为 从 Googlebot 发 出 ， 发 送 到 你 的 服务 器 上 。 因 此 ， 你 必须 正确 配置 你 的 
服务 器 上 的 robots.txt 文件 来 允许 这 些 请 求 。 


例如 ， 下 面 的 robots.txt 指示 向 你 展示 ， 如 何 允 许 你 网 站 上 的 特定 目录 (如 /api/ ) 能 被 你 的 
app 访 问 ， 并 限制 Googlebot 访 问 你 的 网 站 上 的 其 他 目录 。 


User-Agent: Googlebot 
Allow: /api/ 
Disallow: / 


为 索引 指定 App 内 容 


学 习 更 多 关于 如 何 修改 robots.txt ， 来 控制 页 面 抓 取 ， 详 见 Controlling Crawling and 
Indexing Getting Started ° 
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Androidi- d iX it 


These classes teach you how to build a user interface using Android layouts for all types of 
devices. Android provides a flexible framework for UI design that allows your app to display 
different layouts for different devices, create custom UI widgets, and even control aspects of 
the system UI outside your app's window. 


Designing for Multiple Screens 


How to build a user interface that's flexible enough to fit perfectly on any screen and how to 
create different interaction patterns that are optimized for different screen sizes. 


Creating Custom Views 


How to build custom UI widgets that are interactive and smooth. 


Creating Backward-Compatible Uls 


How to use Ul components and other APIs from the more recent versions of Android while 
remaining compatible with older versions of the platform. 


Implementing Accessibility 


How to make your app accessible to users with vision impairment or other physical 
disabilities. 


Managing the System UI 


How to hide and show status and navigation bars across different versions of Android, while 
managing the display of other screen components. 


Creating Apps with Material Design 


How to implement material design on Android. 


Z < a yu x 
为 多 屏幕 设计 
编写 :riverfeng - Æ xc:http://developer.android.com/training/multiscreen/index.html 


从 小 屏 手 机 到 大 屏 电 视 ，android 拥 有 数 百 种 不 同 屏幕 尺寸 的 设备 。 因 此 ， 设 计 兼 容 不 同 屏幕 
尺寸 的 应 用 程序 满足 不 同 的 用 户 体验 就 变 得 非常 重要 


但 是 ， 只 是 单纯 的 兼容 不 同 的 设备 类 型 是 远 远 不 够 的 。 每 个 不 同 的 屏幕 尺寸 都 给 用 户 体验 带 
来 不 同 的 可 能 性 和 挑战 。 所 以 ， 为 了 充分 的 满足 和 打动 用 户 ， 你 的 应 用 不 仅 要 支持 多 屏幕 ， 
更 要 针对 每 个 屏幕 配置 优化 你 的 用 户 体验 。 


这 个 课程 就 将 教 你 如 何 针对 不 同 屏幕 配置 来 优化 你 的 Ul。 


本 课程 提供 了 一 个 简单 的 示例 NewsReader。 这 个 示例 中 每 节 课 的 代码 展示 了 如 何 更 好 的 优化 
多 屏幕 适 配 ， 你 也 可 以 将 这 个 示例 中 的 代码 运用 到 你 自己 的 项 目 中 。 


Note : 这 节 课 中 相关 的 例子 为 了 兼容 android 3.0 以 下 的 版 本 使 用 了 support library 中 的 
Fragment 相 关 APls。 在 使 用 该 示例 前 ， 请 先 确 定 support library 已 经 添加 到 你 的 应 用 中 。 


Lessons 


e 支持 不 同 屏幕 尺寸 


这 节 课 程 将 引导 你 如 何 设计 适 配 多 种 不 同 尺寸 的 布局 (通过 使 用 灵活 的 尺寸 规格 
guige (dimensions) ， 相 对 布局 (RelativeLayout) ， 屏 幕 尺 寸 和 方向 限定 
(qualifiers) ， 别 名 过 滤器 (alias filter) 和 点 9 图 片 ) ° 

e 支持 不 同 的 屏幕 密度 


这 节 课程 将 演示 如 何 支持 不 同 像素 密度 度 的 屏幕 (使 用 密度 独立 像素 (dip) 以 及 为 不 同 的 
密度 提供 合适 的 位 图 (bitmap) ) 。 


m ey 


e 实现 自 适 应 UI| 流 (Flows) 


这 节 课 将 演示 如 何以 UIl 流 (flow) 的 方式 来 适 配 一 些 屏 幕 大 小 /密度 组 合 (动态 布局 运行 
时 检测 ， 响 应 当前 布局 ， 处 理 屏幕 配置 变化 ) 。 


支持 不 同 的 屏幕 大 小 


编写 :riverfeng - Æ X:http://developer.android.com/training/multiscreen/screensizes.html 
这 节 课 教 你 如 何 通过 以 下 几 种 方式 支持 多 屏幕 : 
1、 确 保 你 的 布局 能 自 适应 屏幕 
2、 根 据 你 的 屏幕 配置 提供 合适 的 Ul 布 局 
3、 确 保 正确 的 布局 适合 正确 的 屏幕 。 


4、 提 供 缩放 正确 的 位 图 (bitmap) 


使 用 “wrap_content"” 和 “match_ parent" 


为 了 确保 你 的 布局 能 灵活 的 适应 不 同 的 屏幕 尺寸 ， 针 对 一 些 view 组 件 ， 你 应 该 使 用 
wrap_content 和 match_parent 来 设置 他 们 的 帘 和 高 。 如 果 你 使 用 了 wrap_content，view 的 宽 
和 高 会 被 设置 为 该 view 所 包含 的 内 容 的 大 小 值 。 如 果 是 match_parent〈 在 API 8 之 前 是 

fill parent) 则 会 匹配 该 组 件 的 父 控件 的 大 小 。 


通过 使 用 wrap_content 和 match_parent 尺 寸 值 代 替 硬 编码 的 尺寸 ， 你 的 视图 将 分 别 只 使 用 控 
件 所 需要 的 空间 或 者 被 拓展 以 填充 所 有 有 效 的 空间 。 比 如 : 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:orientation-"vertical" 
android: layout_width="match_parent" 
android: layout_height="match_parent"> 
<LinearLayout android:layout width-"match parent" 
android: id="@+id/linearLayouti" 
android: gravity="center" 
android: layout_height="50dp"> 
<ImageView android: id="@+id/imageView1" 
android: layout_height="wrap_content" 
android: layout_width="wrap_content" 
android: src="@drawable/logo" 
android: paddingRight="30dp" 
android: layout_gravity="left" 
android: layout_weight="0" /> 
«View android:layout height-"wrap content" 
android:id-z"Q-id/view1" 
android: layout_width="wrap_content" 
android: layout_weight="1" /> 
«Button android: id="@+id/categorybutton" 
android: background="@drawable/button_bg" 
android:layout height-"match parent" 
android: layout_weight="0" 
android: layout_width="120dp" 
style="@style/CategoryButtonStyle"/> 
</LinearLayout> 


«fragment android: id="@+id/headlines" 
android:layout height-"fill parent" 
android:name="com.example.android.newsreader .HeadlinesFragment" 
android: layout_width="match_parent" /> 
</LinearLayout> 


注意 上 面 的 例子 使 用 wrap_content 和 match_parent 来 指定 组 件 尺寸 而 不 是 使 用 国定 的 尺寸 。 
这 样 就 能 使 你 的 布局 正确 的 适 配 不 同 的 屏幕 尺寸 和 屏幕 方向 〈 这 里 的 配置 主要 是 指 屏幕 的 横 
坚 屏 切换 ) e 


例如 ， 下 图 演示 的 就 是 该 布局 在 竖 屏 和 横 屏 模式 下 的 效果 ， 注 意 组 件 的 尺寸 是 自动 适应 宽 和 


高 的 。 


800 
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图 1 : News Reader 示 例 app (左边 坚 屏 ， 右 边 横 屏 ) 。 


使 用 相对 布局 (RelativeLayout) 


你 可 以 使 用 LinearLayout 以 及 wrap_content 和 match_parent 组 合 来 构建 复杂 的 布局 ， 但 是 





LinearLayout 却 不 允许 你 精准 的 控制 它 子 view 的 关系 ， 子 view 在 LinearLayout 中 只 能 简单 一 个 
接 一 个 的 排 成 行 。 如 果 你 需要 你 的 子 view 不 只 是 简 简单 单 的 排 成 行 的 排列 ， 更 好 的 方法 是 使 
用 RelativeLayout， 它 允许 你 指定 你 布局 中 控件 与 控件 之 间 的 关系 ， 比 如 ， 你 可 以 指定 一 个 子 


View 在 左边 ， 另 一 个 则 在 屏幕 的 右边 。 


Q4 
oU1 


<?xml version="1.0" encoding="utf-8"?> 
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" 
android: layout_width="match_parent" 
android: layout_height="match_parent"> 
<TextView 
android: id="@+tid/label" 
android: layout_width="match_parent" 
android: layout_height="wrap_content" 
android: text="Type here:"/> 
<EditText 
android:id="@+id/entry" 
android: layout_width="match_parent" 
android: layout_height="wrap_content" 
android: layout_below="@id/label"/> 
<Button 
android: id="@+id/ok" 
android: layout_width="wrap_content" 
android: layout_height="wrap_content" 
android: layout_below="@id/entry" 
android: layout_alignParentRight="true" 
android: layout_marginLeft="10dp" 
android: text="0K" /> 
<Button 
android: layout_width="wrap_content" 
android: layout_height="wrap_content" 
android: layout_toLeftOf="@id/ok" 
android: layout_alignTop="@id/ok" 
android: text="Cancel" /> 
</RelativeLayout> 





EE = 一 一 
图 2 : QVGA (小 尺寸 屏幕 ) 屏幕 下 截图 





图 3 : WSVGA (大 尺寸 屏幕 ) 屏幕 下 截图 


使 用 尺寸 限定 词 


(EAE: 这 里 的 限定 词 主要 是 指 在 编写 布局 文件 时 ， 将 布局 文件 放 在 加 上 类 似 large， 
sw600dp 等 这 样 限定 词 的 文件 夹 中 ， 以 此 来 告诉 系统 根据 屏幕 选择 对 应 的 布局 文件 ， 比 如 下 
面 例子 的 layout-large 文 件 夹 ) 


从 上 一 节 的 学 习 里 程 中 ， 我 们 知道 如 何 编写 灵活 的 布局 或 者 相对 布局 ， 它 们 都 能 通过 拉 伸 或 
者 填充 控件 来 适应 不 同 的 屏幕 ， 但 是 它们 却 不 能 为 每 个 不 同 屏幕 尺寸 提供 最 好 的 用 户 体验 。 
因此 ， 你 的 应 用 不 应 该 只 是 实现 灵活 的 布局 ， 同 时 也 应 该 为 不 同 的 屏幕 配置 提供 几 种 不 同 的 
布局 方式 。 你 可 以 通过 配置 限定 (configuration qualifiers) 来 做 这 件 事 情 ， 它 能 在 运行 时 根 
据 你 当前 设备 的 配置 ( 比如 不 同 的 屏幕 尺寸 设计 了 不 同 的 布局 ) 来 选择 合适 的 布局 资源 。 


比如 ， 很 多 应 用 都 为 大 屏幕 实现 了 “两 个 窗 格 "模式 (应 用 可 能 在 一 个 窗 格 中 实现 一 个 list 的 
item， 另 外 一 个 则 实现 list 的 content) ， 平 板 和 电视 都 是 大 到 能 在 一 个 屏幕 上 适应 两 个 窗 格 ， 
但 是 手机 屏幕 却 只 能 分 别 显 示 。 所 以 ， 如 果 你 想 实 现 这 些 布 局 ， 你 就 需要 以 下 文件 : 


res/layout/main.xml.3X- 4- 4 & (RU) 布局 : 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:orientation="vertical" 
android: layout_width="match_parent" 
android: layout_height="match_parent"> 


«fragment android: id="@+tid/headlines" 
android:layout height-"fill parent" 
android:name="com.example.android.newsreader .HeadlinesFragment" 
android: layout_width="match_parent" /> 
</LinearLayout> 


res/layout-large/main.xml, 两 个 窗 格 布局 : 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:layout width-"fill parent" 
android:layout height-"fill parent" 
android:orientation-"horizontal"» 
«fragment android:id="@+tid/headlines" 
android:layout height-"fill parent" 
android:name="com.example.android.newsreader .HeadlinesFragment" 
android: layout_width="400dp" 
android: layout_marginRight="10dp"/> 
«fragment android: id="@+id/article" 
android:layout height-"fill parent" 
android:name="com.example.android.newsreader .ArticleFragment" 
android: layout_width="fill_parent" /> 
</LinearLayout> 


注意 第 二 个 布局 文件 的 目录 名 字 “large qualifier， 在 大 尺寸 的 设备 屏幕 时 〈 比 如 7 寸 平 板 或 者 
其 他 大 屏幕 的 设备 ) 就 会 选择 该 布局 文件 ， 而 其 他 比较 小 的 设备 则 会 选择 没有 限定 词 的 另 一 
个 布局 (也 就 是 第 一 个 布局 文件 ) 。 


使 用 最 小 宽度 限定 词 


在 Android 3.2 之 前 ， 开 发 者 还 有 一 个 困难 ， 那 就 是 Android 设 备 的 4arge" 屏 幕 尺 寸 ， 其 中 包括 
Dell Streak (设备 名 称 ) ， 老 版 Galaxy Tab 和 一 般 的 7 寸 平 板 ， 有 很 多 的 应 用 都 想 针 对 这 些 不 
同 的 设备 〈 比 如 5 和 7 寸 的 设备 ) 定义 不 同 的 布局 ， 但 是 这 些 设备 都 被 定义 为 了 large 尺 寸 屏 
幕 。 也 是 因为 这 个 ， 所 以 Android 在 3.2 的 时 候 开始 使 用 最 小 宽度 限定 词 。 

最 小 宽度 限定 词 允许 你 根据 设备 的 最 小 宽度 (dp 单位 ) 来 指定 不 同 布局 。 比 如 ， 传 统 的 7 寸 平 
板 最 小 宽度 为 600dp， 如 果 你 希望 你 的 UI 能 够 在 这 样 的 屏幕 上 显示 两 个 窗 格 (不 是 一 个 窗 格 显 
示 在 小 屏幕 上 ) ， 你 可 以 使 用 上 节 中 提 到 的 使 用 同样 的 两 个 布局 文件 。 不 同 的 是 ， 使 用 sw600 
来 指定 两 个 方 框 的 布局 使 用 在 最 小 宽度 为 600dp 的 设备 上 。 


res/layout/main.xml, 单 个 窗 格 (上 默认) 布局 : 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:orientation="vertical" 
android: layout_width="match_parent" 
android: layout_height="match_parent"> 


«fragment android: id="@+tid/headlines" 
android:layout height-"fill parent" 
android:name="com.example.android.newsreader .HeadlinesFragment" 
android: layout_width="match_parent" /> 
</LinearLayout> 


res/layout-sw600dp/main.xml, 7 4- Zr 4E 7/5] : 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:layout width-"fill parent" 
android:layout height-"fill parent" 
android:orientation-"horizontal"» 
«fragment android:id="@+tid/headlines" 
android:layout height-"fill parent" 
android:name="com.example.android.newsreader .HeadlinesFragment" 
android: layout_width="400dp" 
android: layout_marginRight="10dp"/> 
«fragment android: id="@+id/article" 
android:layout height-"fill parent" 
android:name="com.example.android.newsreader .ArticleFragment" 
android: layout_width="fill_parent" /> 
</LinearLayout> 


这 样 意味 着 当 你 的 设备 的 最 小 宽度 等 于 600dp 或 者 更 大 时 ， 系 统 选择 layout- 
sw600dp/main.xml (两 个 窗 格 ) 的 布局 ， 而 小 一 点 的 屏幕 则 会 选择 layout/main.xml (单个 窗 
格 ) 的 布局 。 然 而 ， 在 3.2 之 前 的 设备 上 ， 这 样 做 并 不 是 很 好 的 选择 。 因 为 3.2 之 前 还 没有 将 
sw600dp 作 为 一 个 限定 词 出 现 ， 所 以 ， 你 还 是 需要 使 用 large 限 定 词 来 做 。 因 此 ， 你 还 是 应 该 
要 有 一 个 布局 文件 名 为 res/layout-large/main.xml， 和 res/layout-sw600dp/main.xml 一 样 。 在 
下 一 节 中 ， 你 将 学 到 如 何 避 免 像 这 样 出 现 重复 的 布局 文件 。 


使 用 布局 别名 


最 小 宽度 限定 词 只 能 在 android3.2 或 者 更 高 的 版 本 上 使 有 用。 因此， 你 还 是 需要 使 用 抽象 尺寸 
(small，normal，large，xlarge) 来 兼容 以 前 的 版 本 。 比 如 ， 你 想 要 将 你 的 UI 设 计 为 在 手机 
上 只 显示 一 个 方 框 的 布局 ， 而 在 7 寸 平 板 或 电视 ， 或 者 其 他 大 屏幕 设备 上 显示 多 个 方 框 的 布 
局 ， 你 可 能 得 提供 这 些 文件 : 


e res/layout/main.xml : 单个 窗 格 布局 


e res/layout-large : 多 个 窗 格 布局 


e res/layout-sw600dp : 多 个 窗 格 布局 


最 后 两 个 文件 都 是 一 样 的 ， 因 为 其 中 一 个 将 会 适 配 Android3.2 的 设备 ， 而 另外 一 个 则 会 适 配 其 
他 Android 低 版 本 的 平板 或 者 电视 。 为 了 避免 这 些 重 复 的 文件 (维护 让 人 感觉 头痛 就 是 因为 这 
个 ) ， 你 可 以 使 用 别名 文件 。 比 如 ， 你 可 以 定义 如 下 布局 : 


。 res/layout/main.xml * * 4- Z 4E 7/5] 
e res/layout/main twopans.xml > R 4- Z 1E 7p Ay 


然后 添加 这 两 个 文件 : 


e res/values-large/layout.xml : 


«resources» 
«item name-"main" type="layout">@layout/main_twopanes</item> 
«/resources» 


e res/values-sw600dp/layout.xml : 


«resources» 
«item name-"main" type="Layout">@layout/main_twopanes</item> 
</resources> 


REASLHMAM AMAR ENARA AELA EHR 
main_twopanes 设 置 成 为 了 别名 main， 它 们 分 别处 在 large 和 sw600dp 选 择 器 中 ， 所 以 它 
们 能 适 配 Android 任 何 版 本 的 平板 和 电视 〈 在 3.2 之 前 平板 和 电视 可 以 直接 匹配 large， 而 
3.2 或 者 以 上 的 则 匹配 sw600dp) ° 


使 用 方向 限定 词 


有 一 些 布局 不 管 是 在 横向 还 是 纵向 的 屏幕 配置 中 都 能 显示 的 非常 好 ， 但 是 更 多 的 时 候 ， 适 当 
的 调整 一 下 会 更 好 。 在 News Reader 应 用 例子 中 ， 以 下 是 布局 在 不 同 屏 幕 尺 寸 和 方向 的 行 
A: 


小 屏幕 ， 纵 向 : 一 个 窗 格 加 logo 

小 屏幕 ， 横 向 : 一 个 窗 格 加 logo 

7 二 平板， 纵向 : 一 个 窗 格 加 action bar 

7 十 平板 ， 横 向 : 两 个 宽 窗 格 加 action bar 
10 寸 平板 ， 纵 向 : 两 个 窒 窗 格 加 action bar 
10 寸 平板 ， 横 向 : 两 个 宽 窗 格 加 action bar 
e 电视 ， 横 向 : 两 个 宽 窗 格 加 action bar 


这 些 每 个 布局 都 会 在 res/layout 目 录 下 定义 一 个 xml 文 件 ， 如 此 ， 应 用 就 能 根据 屏幕 配置 的 变化 
根据 别名 匹配 到 对 应 的 布局 来 适应 屏幕 。 


兼容 不 同 的 屏幕 大 小 


res/layout/onepane.xml : 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 


android:orientation-'"vertical" 


android: layout_width="match_parent" 
android: layout_height="match_parent"> 


«fragment android: id="@+id/headlines" 


android:layout height-"fill parent" 


android:name="com.example.android.newsreader .HeadlinesFragment" 


android: layout_width="match_parent" /> 


</LinearLayout> 


res/layout/onepane_with_bar.xml: 


<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 


android: orientation="vertical" 
android: layout_width="match_parent" 


android: layout_height="match_parent"> 
<LinearLayout android:layout width-"match parent" 
android:id-"Q-id/linearLayout1i" 


android:gravity-"center" 
android: layout_height="50dp"> 


<ImageView android 
android 
android 


android: 
android: 


android 
android 


:id="@+tid/imageView1" 
:layout height-"wrap content" 
:layout width-"wrap content" 


src="@drawable/logo" 
paddingRight="30dp" 


:layout gravity-"left" 
:layout weight-"0" /> 


«View android:layout height-"wrap content" 
android:id-"Q-id/view1" 


android: layout_width="wrap_content" 


android: layout_weight="1" /> 
«Button android: id="@+id/categorybutton" 
android: background="@drawable/button_bg" 


android:layout height-"match parent" 


android: layout_weight="0" 
android: layout_width="120dp" 
style="@style/CategoryButtonStyle"/> 


</LinearLayout> 


«fragment android: id="@+id/headlines" 
android:layout height-"fill parent" 


android:name="com.example.android.newsreader .HeadlinesFragment" 


android: layout_width="match_parent" /> 


</LinearLayout> 


res/layout/twopanes.xml: 


807 





«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 


android:layout width-"fill parent" 


android:layout height-"fill parent" 


android:orientation-"horizontal"» 


«fragment android: 


android 


android: 
: Layout_width="400dp" 
: Layout_marginRight="10dp"/> 


android 
android 


<fragment android: 
:layout height-"fill parent" 


android 


android: 
:layout width-"fill parent" /> 


android 
</LinearLayout> 


id="@+id/headlines" 


:layout height-z"fill parent" 


name-"com.example.android.newsreader.HeadlinesFragment" 


id="@+id/article" 


name="com.example.android.newsreader .ArticleFragment" 


res/layout/twopanes_narrow.xml: 


<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 
android:layout width-"fill parent" 
android:layout height-"fill parent" 


android:orientation-"horizontal"» 


«fragment android: 


android 


android: 
: Layout_width="200dp" 
: Layout_marginRight="10dp"/> 


android 
android 


<fragment android: 


android 


android: 
:layout width-"fill parent" /> 


android 
</LinearLayout> 


现在 所 有 可 能 的 布局 我 们 都 已 经 定义 了 ， 唯 一 剩 下 的 问题 是 使 用 方向 限定 词 来 匹配 对 应 的 布 


id="@+id/headlines" 


:layout height-"fill parent" 


name-"com.example.android.newsreader.HeadlinesFragment" 


id="@+id/article" 


:layout_height="fill_parent" 


name="com.example.android.newsreader .ArticleFragment" 


局 给 屏幕 。 这 时 候 ， 你 就 可 以 使 用 布局 别名 的 功能 了 : 


res/values/layouts.xml : 


«resources» 


«item name-"main layout" type="layout">@layout/onepane_with_bar</item> 


«bool name="has_two_panes">false</bool> 


«/resources» 


res/values-sw600dp-land/layouts.xml: 


«resources» 
«item name-"main layout" type="layout">@layout/twopanes</item> 
«bool name="has_two_panes">true</bool> 

«/resources» 


res/values-sw600dp-port/layouts.xml: 


«resources» 
«item name-"main layout" type="layout">@layout/onepane</item> 
«bool name="has_two_panes">false</bool> 

«/resources» 


res/values-large-land/layouts.xml: 


«resources» 
«item name-"main layout" type="layout">@layout/twopanes</item> 
«bool name="has_two_panes">true</bool> 

</resources> 


res/values-large-port/layouts.xml: 


«resources» 
«item name-"main layout" type="layout">@layout/twopanes_narrow</item> 
«bool name="has_two_panes">true</bool> 

«/resources» 


使 用 .9.png 图 片 
支持 不 同 的 屏幕 尺寸 同时 也 意味 着 你 的 图 片 资 源 也 必须 能 兼容 不 同 的 屏幕 尺寸 。 比 如 ， 一 个 
button 的 背景 图 片 就 必须 要 适应 该 button 的 各 种 形状 。 


如 果 你 在 使 用 组 件 时 可 以 改变 图 片 的 大 小 ， 你 很 快 就 会 发 现 这 是 一 个 不 明确 的 选择 。 因 为 运 
行 的 时 候 ， 图 片 会 被 拉 伸 或 者 压缩 (这样 容易 造成 图 片 失 睫 )。 人 避免 这 种 情况 的 解决 方案 就 
是 使 用 点 9 图 片 ， 这 是 一 种 能 够 指定 哪些 区 域 能 够 或 者 不 能 够 拉 伸 的 特殊 png 文 件 。 


因此 ， 在 设计 的 图 片 需要 与 组 件 一 起 变 大 变 小 时 ， 一 定 要 使 用 点 9. 若 要 将 位 图 转换 为 点 9， 你 





可 以 用 一 个 普通 的 图 片 开 始 〈 下 图 ， 是 在 4 倍 变 焦 情 况 下 的 图 片 显 示 ) 。 


Onn 
OUY 


兼容 不 同 的 屏幕 大 小 


你 可 以 通过 sdk 中 的 draw9patch 程 序 dos ue an XT) 来 画 点 9 图 片 。 通 过 沿 左 侧 
和 顶部 边框 绘制 像素 来 标记 应 该 被 拉 伸 的 区 域 。 也 可 以 通过 洛 右 侧 和 底部 边界 绘制 像素 来 标 
记 。 就 像 下 图 所 示 一 样 : 





请 注意 ， 上 图 沿边 界 的 黑色 像素 。 在 顶部 边框 和 左边 框 的 那些 表明 图 像 的 可 拉 伸 区 域 ， 右 边 
和 底部 边框 则 表示 内 容 应 该 放置 的 地 方 。 


此 外 ， 注 意 .9.png 这 个 格式 ， 你 也 必须 用 这 个 格式 ， 因 为 系统 会 检测 这 是 一 个 点 9 图 片 而 不 是 
一 个 普通 PNG 图 片 。 


你 将 这 个 应 用 到 组 件 的 背景 的 时 候 (通过 设置 
en en > android 框 架 会 自动 正确 的 拉 伸 图 像 以 适应 按钮 
的 大 小 ， 下 图 就 是 各 种 尺寸 中 的 显示 效果 : 
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FEA PO Ap a PL 


编写 :riverfeng - 原 
X :http://developer.android.com/training/multiscreen/screendensities.html 


33 7E R BA do T 388 RE HF 83 ER e [LR ATIE (dp) 来 支持 不 同 的 屏幕 密度 


使 用 密度 独立 像素 (dp) 


设计 布局 时 ， 要 避免 使 用 绝对 像素 (absolutepixels) 定义 距离 和 尺寸 。 使 用 像素 单位 来 定义 
布局 大 小 是 有 问题 的 。 因 为 ， 不 同 的 屏幕 有 不 同 的 像素 密度 ， 所 以 ， 同 样 单位 的 像素 在 不 同 
的 设备 上 会 有 不 同 的 物理 尺寸 。 因 此 ， 在 指定 单位 的 时 候 ， 通 常 使 用 dp 或 者 sp。 一 个 dp 代表 
一 个 密度 独立 像素 ， 也 就 相当 于 在 160 dpi 的 一 个 像素 的 物理 尺寸 ，sp 也 是 一 个 基本 的 单位 ， 
不 过 它 主要 是 用 在 文本 尺寸 上 ( 它 也 是 一 种 尺寸 规格 独立 的 像素 ) ， 所 以 ， 你 在 定义 文本 尺 
寸 的 时 候 应 该 使 用 这 种 规格 单位 (不 要 使 用 在 布 尺寸 上 ) © 


例如 ， 当 你 是 定义 两 个 view 之 间 的 空间 时 ， 应 该 使 用 dp 而 不 是 px : 


«Button android:layout width="wrap_content" 
android:layout height-"wrap content" 
android: text="@string/clickme" 
android: layout_marginTop="20dp" /> 


当 指 定 文本 尺寸 时 ， 始 终 应 该 使 用 sp : 


<TextView android: layout_width="match_parent" 
android:layout height-"wrap content" 
android:textSize-"20sp" /» 


提供 选择 的 图 上 


因为 Android 能 运行 在 很 多 不 同 屏幕 密度 的 设备 上 ， 所 以 ， 你 应 该 针对 不 同 的 设备 密度 提供 不 
同 的 bitmap 资 源 : 小 屏幕 (low) ，medium (中 ) ，high (高 ) 以 及 超 高 (extra-high) X 
这 将 能 帮助 你 在 所 有 的 屏幕 密度 中 得 到 非常 好 的 图 形 质 量 和 性 能 。 


为 了 提供 更 好 的 用 户 体验 ， 你 应 该 使 用 以 下 几 种 规格 来 缩放 图 片 大 小 ， 为 不 同 的 屏幕 密度 提 
供 相 应 的 位 图 资源 : 


xhdpi:2.0 
hdpi:1.5 
mdpi:1.0( 标 准 线 ) 
ldpi:0.75 


这 也 就 意味 着 如 果 在 Xxhdpi 设 备 上 你 需要 一 个 200x200 的 图 片 ， 那 么 你 则 需要 一 张 150x150 的 
图 片 用 于 hdpi，100x100 的 用 于 mdpi 尺 及 75x75 的 用 户 ldpi 设 备 。 


然后 将 这 些 图 片 资 源 放 到 res/ 对 应 的 目录 下 面 ， 系 统 会 自动 根据 当前 设备 屏幕 密度 自动 去 选择 
合适 的 资源 进行 加 载 : 


MyProject/ 
res/ 

drawable-xhdpi/ 
awesomeimage.png 

drawable-hdpi/ 
awesomeimage.png 

drawable-mdpi/ 
awesomeimage.png 

drawable-ldpi/ 
awesomeimage.png 


这 样 放置 图 片 资 源 后 ， 不 论 你 什么 时 候 使 用 @drawable/awesomeimage， 系 统 都 会 给 予 屏 幕 
的 dp 来 选择 合适 的 图 片 。 


如 果 你 想 知 道 更 多 关于 如 何 为 你 的 应 用 程序 创建 icon 资 源 ， 你 可 以 看 看 Icon 设计 指南 |con 
Design Guidelines. 


实现 自 适 应 UI 流 (Flows) 


编写 :riverfeng - Æ xc:http://developer.android.com/training/multiscreen/adaptui.html 


根据 当前 你 的 应 用 显示 的 布局 ， 它 的 UI 流 可 能 会 不 一 样 。 比 如 ， 当 你 的 应 用 是 双 窗 格 模式 ， 
点 击 左边 窗 格 的 条 目 (item) 时 ， 内 容 (content) 显示 在 右边 窗 格 中 。 如 果 是 单 窗 格 模式 
中 ， 当 你 点 击 某 个 item 的 时 候 ， 内 容 则 显示 在 一 个 新 的 activity 中 。 


确定 当前 布局 


由 于 每 种 布局 的 实现 会 略 有 差别 ， 首 先 你 可 能 要 确定 用 户 当 前 可 见 的 布局 是 哪 一 个 。 比 如 ， 
你 可 能 想 知 道 cu E 式 还 是 “ 双 窗 格 "的 模式 。 你 可 以 通过 检查 指定 
的 视图 (view) 是 否 存 在 和 可 见 来 实现 : 


public class NewsReaderActivity extends FragmentActivity 1 


boolean mIsDualPane; 


@Override 

public void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
setContentView(R.layout.main layout); 


View articleView - findViewById(R.id.article); 
mIsDualPane = articleView != null && 
articleView.getVisibility() -- View.VISIBLE; 


注意 : 使 用 代码 查询 jd 为 “article” 的 view 是 否 可 见 比 直接 硬 编码 查询 指定 的 布局 更 加 的 灵 
Xx e 


另 一 个 关于 如 何 适 配 不 同 组 件 是 否 存在 的 例子 ， 是 在 组 件 执行 操作 之 前 先 检查 它 是 否 是 可 用 
的 。 比 如 ， 在 News Reader 示 例 中 ， 有 一 个 按钮 点 击 后 打开 一 个 菜单 ， 但 是 这 个 按钮 仅仅 只 
在 Android3.0 之 后 的 版 本 中 才能 显示 〈 因 为 这 个 功能 被 ActionBar 人 代替， 在 API 11+ 中 定义 ) ° 
所 以 ， 在 给 这 个 按钮 添加 事件 之 间 ， 你 可 以 这 样 做 : 


Button catButton = (Button) findViewById(R.id.categorybutton); 
OnClickListener listener - /* create your listener here */; 


if (catButton != null) { 
catButton.setOnClickListener(listener); 


根据 当前 布局 响应 


一 些 操 作 会 根据 当前 的 布局 产生 不 同 的 效果 。 比 如 ， 在 News Reader 示 例 中 ， 当 你 点 击 标题 
(headlines ) nl diei dis 如 果 你 的 UI 是 双 窗 格 模式 ， 内 容 会 显示 在 右边 的 
窗 格 中 ， 如 果 你 的 Ul 是 单 窗 格 模式 ， 会 启动 一 个 分 开 的 Activity 并 显示 : 


@Override 
public void onHeadlineSelected(int index) { 
mArtIndex = index; 
if (mIsDualPane) { 
/* display article on the right pane */ 
mArticleFragment.displayArticle(mCurrentCat.getArticle(index)); 
} else { 
/* start a separate activity */ 
Intent intent = new Intent(this, ArticleActivity.class); 
intent.putExtra("catIndex", mCatIndex); 
intent.putExtra("artIndex", index); 
startActivity(intent); 


同样 ， 如 果 你 的 应 用 处 于 多 窗 格 模 那么 它 应 该 在 导航 栏 中 设置 带 有 选项 卡 的 action bar。 
而 如 果 是 单 窗 格 模式 ， 那 么 导航 栏 应 该 设置 为 spinner widget。 所 以 ， 你 的 代码 应 该 检查 哪个 
方案 是 最 合适 的 : 


final String CATEGORIES[] = { "Top Stories", "Politics", "Economy", "Technology" }; 
public void onCreate(Bundle savedInstanceState) { 


if (mIsDualPane) { 
/* use tabs for navigation */ 
actionBar.setNavigationMode(android.app.ActionBar.NAVIGATION MODE TABS); 
alae ale 
for (i = 0; i < CATEGORIES.length; i++) { 
actionBar .addTab(actionBar .newTab().setText ( 
CATEGORIES[i]).setTabListener(handler)); 


} 
actionBar.setSelectedNavigationItem(selTab); 

} 

else f 
/* use list navigation (spinner) */ 
actionBar.setNavigationMode(android.app.ActionBar.NAVIGATION MODE LIST); 
SpinnerAdapter adap - new ArrayAdapter(this, 

R.layout.headline item, CATEGORIES); 

actionBar.setListNavigationCallbacks(adap, handler); 

} 


在 其 他 Activity 中 复 用 Fragment 


在 多 屏幕 设计 时 经 常 出 现 的 情况 是 : 在 一 些 屏幕 配置 上 设计 一 个 窗 格 ， 而 在 其 他 屏幕 配置 上 
启动 一 个 独立 的 Activity。 例 如 ， 在 News Reader 中 ， 新 闻 内 容 文字 在 大 屏幕 上 市 显示 在 屏幕 
右边 的 方 框 中 ， 而 在 小 屏幕 中 ， 则 是 由 单独 的 activity 显 示 的 。 


像 这 样 的 情况 ， 你 就 应 该 在 不 同 的 activity 中 使 用 同一 个 Fragment， 以 此 来 避免 代码 的 重复 ， 
而 达到 代码 复 用 的 效果 。 比 如 ，ArticleFragment 在 双 窗 格 模式 下 是 这 样 用 的 : 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:layout widthz"fill parent" 
android:layout height-"fill parent" 
android:orientation-"horizontal"» 
«fragment android:id-"Q-*-id/headlines" 
android:layout height-"fill parent" 
android:name="com.example.android.newsreader .HeadlinesFragment" 
android: layout_width="400dp" 
android: layout_marginRight="10dp"/> 
«fragment android: id="@+id/article" 
android:layout height-"fill parent" 
android:name="com.example.android.newsreader .ArticleFragment" 
android: layout_width="fill_parent" /> 
</LinearLayout> 


在 小 屏幕 中 ， 它 又 是 如 下 方式 被 复 用 的 《没有 布局 文件 ) 


ArticleFragment frag = new ArticleFragment(); 
getSupportFragmentManager().beginTransaction().add(android.R.id.content, frag).commit( 


) 


当然 ， 如 果 将 这 个 fragment 定义 在 XML 布局 文件 中 ， 也 有 同样 的 效果 ， 但 是 在 这 个 例子 中 ， 
则 没有 必要 ， 因 为 这 个 article fragment 是 这 个 activity 的 唯一 组 件 。 


人 时 候 ， 非 常 重要 的 一 点 : 不 要 为 菜 个 特定 的 activity 设 计 耦 合 度 高 的 
fragment。 通 常 的 做 法 是 ， 通 过 定义 抽象 接口 ， 并 在 接口 中 定义 需要 与 该 fagment 进 行 交 互 的 
activity 的 抽象 方法 ， 然 后 与 该 fagment 进 行 交 互 的 activity 实 现 这 些 抽象 接口 方法 。 


例如 ， 在 News Reader 中 ，HeadlinesFragment 就 很 好 的 诠释 了 这 


public class HeadlinesFragment extends ListFragment { 
OnHeadlineSelectedListener mHeadlineSelectedListener = null; 


/* Must be implemented by host activity */ 
public interface OnHeadlineSelectedListener { 
public void onHeadlineSelected(int index); 


public void setOnHeadlineSelectedListener(OnHeadlineSelectedListener listener) ( 
mHeadlineSelectedListener - listener; 


然后 ， 当 用 户 选择 了 一 个 headline item 之 后 ，fragment 将 通知 对 应 的 activity 指 定 监 听 事 件 
(而 不 是 通过 硬 编码 的 方式 去 通知 ) 


public class HeadlinesFragment extends ListFragment { 


@Override 
public void onItemClick(AdapterView<?> parent, 
View view, int position, long id) { 
if (null != mHeadlineSelectedListener) { 
mHeadlineSelectedListener .onHeadlineSelected(position) ; 


这 种 技术 在 支持 平板 与 手持 设备 (Supporting Tablets and Handsets) 有 更 加 详细 的 介绍 。 


处 理 屏 幕 配置 变化 


如 果 使 用 的 是 单独 的 activity 来 实现 你 界面 的 不 同 部 分 ， 你 需要 注意 的 是 ， 屏 幕 变 化 (如 旋转 
变化 ) 的 时 候 ， 你 也 应 该 根据 屏幕 配置 的 变化 来 保持 你 的 Ul 布 局 的 一 致 性 。 


例如 ， 在 传统 的 Android3.0 或 以 上 版 本 的 7 寸 平板 上 ，News Reader 示 例 在 坚 屏 的 时 候 使 用 独 
立 的 activity 显 示 文 章 内 容 ， 而 在 横 屏 的 时 候 ， 则 使 用 两 个 窗 格 模式 〈 即 内 容 显示 在 右边 的 方 
JEP) 。 这 也 就 意味 着 ， 当 用 户 在 坚 屏 模式 下 观看 文章 的 时 候 ， 你 需要 检测 屏幕 是 否 变 成 了 
横 屏 ， 如 果 改 变 了 ， 则 结束 当前 activity 并 返回 到 主 activity 中 ， 这 样 ，content 就 能 显示 在 双 窗 
格 模式 布局 中 。 


public class ArticleActivity extends FragmentActivity { 
int mCatIndex, mArtIndex; 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
mCatIndex = getIntent().getExtras().getInt("catIndex", 0); 
mArtIndex = getIntent().getExtras().getInt("artIndex", 0); 


// If should be in two-pane mode, finish to return to main activity 
if (getResources().getBoolean(R.bool.has two panes)) { 

finish(); 

return; 


# 创建 自 定 义 View 
编写 :kesenhoo - 原文 :http://developer.android.com/training/custom-views/index.html 


Android 的 ffamework 有 大 量 的 Views 用 来 与 用 户 进行 交互 并 显示 不 同 种 类 的 数据 。 但 是 有 时 候 
你 的 程序 有 个 特殊 的 需求 ， 而 Android 内 置 的 views 组 件 并 不 能 实现 。 这 一 章节 会 演示 如 何 创 
建 你 自己 的 views， 并 使 得 它们 是 robust 与 reusable 的 。 


依赖 和 要 求 
Android 2.1 (API level 7) 或 更 高 
你 也 可 以 看 


e Custom Components 

e |nput Events 

e Property Animation 

e Hardware Acceleration 

e Accessibility developer guide 


Sample 


CustomView.zip 


Lesson 


e 创建 一 个 View 关 

创建 一 个 像 内 置 的 view， 有 自 定 义 属 性 并 支持 ADT layout 编 辑 器 。 
e 自 定 义 Drawing 

使 用 Android graphics 系 统 使 你 的 view 拥 有 独特 的 视觉 效果 。 
e 使 得 View 是 可 交互 的 


用 户 期 望 view 对 操作 反应 流畅 自然 。 这 节 课 会 讨论 如 何 使 用 gesture detection, physics, 
和 animation 使 你 的 用 户 界 面 有 专业 的 水 准 。 


e 优化 View 


不 管 你 的 Ul 如 何 的 漂亮 ， 如 果 不 能 以 高 帧 率 流 畅 运 行 ， 用 户 也 不 会 喜欢 。 学 习 如 何 避 免 
一 般 的 性 能 问题 ， 和 如 何 使 用 硬件 加 速 来 使 你 的 自 定 义 图 像 运 行 更 流畅 。 


创建 自 定 义 View 


819 


# 创建 自 定 义 的 View 类 


编写 :kesenhoo - 原文 :http://developer.android.com/training/custom-views/create- 
view.html 


设计 良好 的 类 总 是 相似 的 。 它 使 用 一 个 好 用 的 接口 来 封装 一 个 特定 的 功能 ， 它 有 效 的 使 用 
CPU 与 内 存 ， 等 等 。 为 了 成 为 一 个 设计 良好 的 类 ， 自 定义 的 view 应 该 : 


e 遵守 Android 标 准 规则 。 

e 提供 自 定义 的 风格 属性 值 并 能 够 被 Android XML Layout 所 识别 。 
e 发 出 可 访问 的 事件 。 

e 能 够 兼容 Android 的 不 同 平台 。 


Android 的 ffamework 提 供 了 许多 基 类 与 XML 标签 用 来 帮助 你 创建 一 个 符合 上 面 要 求 的 View。 
这 节 课 会 介绍 如 何 使 用 Android framework 来 创建 一 个 view 的 核心 功能 。 


继承 一 个 View 


Android framework 里 面 定义 的 view 类 都 继承 自 View。 你 自 定 义 的 view 也 可 以 直接 继承 View ， 
或 者 你 可 以 通过 继承 既 有 的 一 个 子 类 (例如 Button) 来 节约 一 点 时 间 。 


为 了 让 Android Developer Tools 能 够 识别 你 的 view， 你 必须 至 少 提 供 一 个 constructor， 它 包含 
一 个 Contenx 与 一 个 AttributeSet 对 象 作为 参数 。 这 个 constructor 允 许 layout editor 创 建 并 编辑 
你 的 view 的 实例 。 


class PieChart extends View { 
public PieChart(Context context, AttributeSet attrs) { 
super(context, attrs); 


} 


定义 自 定义 属性 


为 了 添加 一 个 内 置 的 View 到 你 的 UI 上 ， 你 需要 通过 XML 属性 来 指定 它 的 样式 与 行为 。 良 好 的 
自 定 义 views 可 以 通过 XML 添加 和 改变 样式 ， 为 了 让 你 的 自 定 义 的 view 也 有 如 此 的 行为 ， 你 应 
该 : 


为 你 的 view 在 资源 标签 下 定义 自 设 的 属性 
在 你 的 XML layout 中 指定 属性 值 

在 运行 时 获取 属性 值 

把 获取 到 的 属性 值 应 用 在 你 的 view 上 


这 一 节 讨 论 如 何 定义 自 定 义 属性 以 及 指定 属性 值 ， 下 一 节 将 会 实现 在 运行 时 获取 属性 值 并 将 
它 应 用 。 

为 了 定义 自 设 的 属性 ， 添 加 资源 到 你 的 项 目 中 。 放 置 于 res/values/attrs.Xxml 文 件 中 。 下 面 是 一 
个 attrs.xml 文 件 的 示例 : 


«resources» 
«declare-styleable name="PieChart"> 
«attr name="ShowText" format="boolean" /> 
<attr name-'"labelPosition" format="enum"> 
<enum name="left" value="0"/> 
<enum name="right" value="1"/> 
</attr> 
</declare-styleable> 


</resources> 


上 面 的 代码 声明 了 2 个 自 设 的 属性 ，showText 与 labelPosition， 它 们 都 归属 于 PieChart 的 项 
目下 的 styleable 实 例 。styleable 实 例 的 名 字 ， 通 常 与 自 定 义 的 view 名 字 一 致 。 尽 管 这 并 没有 严 
格 规定 要 遵守 这 个 convention， 但 是 许多 流行 的 代码 编辑 器 都 依靠 这 个 命名 规则 来 提供 
statement completion ° 


一 旦 你 定义 了 自 设 的 属性 ， 你 可 以 在 layout XML 文件 中 使 用 它们 ， 就 像 内 置 属 性 一 样 。 唯 一 
不 同 的 是 你 自 设 的 属性 是 归属 于 不 同 的 命名 空间 。 不 是 属 

于 http://schemas.android.com/apk/res/android 的 命名 空间 ， 它 们 归属 

于 http://schemas.android.com/apk/res/[your package name] ° 例如 ， 下 面 演示 了 如 何 为 
PieChart 使 用 上 面 定义 的 属性 


<?xml version="1.0" encoding="utf-8"?> 
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 
xmlns:custom="http://schemas.android.com/apk/res/com.example.customviews"> 
<com.example.customviews.charting.PieChart 
custom: showText="true" 
custom: labelPosition="left" /> 


</LinearLayout> 


了 避免 输入 长 囊 的 namespace 名 字 ， 示 例 上 面 使 用 了 xmins 指令 ， 这 个 指令 可 以 指 
派 custom 作为 http://schemas.android.com/apk/res/com.example.customviews namespace #4 $! 
名 。 你 也 可 以 选择 其 他 的 别名 作为 你 的 namespace ° 
请 注意 ， 如 果 你 的 view 是 一 个 inner class， 你 必须 指 iUud ced class » Fh] AE 8 > de 
PieChart 4 — “sinner class 叫 做 PieView。 为 了 使 用 这 个 类 中 自 设 的 属性 ， 你 应 该 使 用 
Ce 


应 用 自 定 义 属 性 


当 View 从 XML layout 被 创建 的 时 候 ， 在 Xml 标签 下 的 属性 值 都 是 从 resource 下 读 取出 来 并 传递 
view 的 constructor 作 为 一 个 AttributeSet 参 数 。 尺 管 可 以 从 AttributeSet 中 直接 读 取 数值 ， 可 
ix EUR edo: 


e 拥有 属性 的 资源 并 没有 经 过 解析 
e Styles 并 没有 运用 上 


翻译 注 : 通过 attrs 的 方法 是 可 以 直接 获取 到 属性 值 的 ， 但 是 不 能 确定 值 类 型 ， 如 : 


String title - attrs.getAttributeValue(null, "title"); 
int resId = attrs.getAttributeResourceValue(null, "title", 0); 
title - context.getText(resId)); 


都 能 获取 到 "title" 属性 ， 但 你 不 知道 值 是 字符 串 还 是 resld， 处 理 起 来 就 容易 出 问题 ， 下 
面 的 方法 则 能 在 编译 时 就 发 现 问题 


取而代之 的 是 ， 通 过 obtainStyledAttributes() 来 获取 属性 值 。 这 个 方法 会 传递 一 个 TypedArray 
对 象 ， 它 是 间接 referenced 并 且 styled 的 。 


Android 资 源 编 译 器 帮 你 做 了 许多 工作 来 使 调用 obtainStyledAttributes()) 更 简单 。 对 res 目 录 里 
的 每 一 个 «declare-styleable» 资源 ， 自 动 生 成 的 R.java 文 件 定义 了 存放 属性 ID 的 数组 和 党 

量 ， 常 量 用 来 索引 数组 中 每 个 属性 。 你 可 以 使 用 这 些 预先 定义 的 常量 来 从 TypedArray 中 读 取 
属性 。 这 里 就 是 piechart 类 如 何 读 取 它 的 属性 


public PieChart(Context context, AttributeSet attrs) { 
super(context, attrs); 
TypedArray a - context.getTheme().obtainStyledAttributes( 
attrs, 
R.styleable.PieChart, 
0, 0); 


tayi 
mShowText = a.getBoolean(R.styleable.PieChart_showText, false); 
mTextPos = a.getInteger(R.styleable.PieChart_labelPosition, 0); 
) finally ( 
a.recycle(); 


j 


清 注 意 TypedArray 对 象 是 一 个 共享 资源 ， 必 须 被 在 使 用 后 进行 回收 。 


性 和 事件 


Attributes 是 一 个 强大 的 控制 view 的 行为 与 外 观 的 方法 ， 但 是 他 们 仅仅 能 够 在 view 被 初始 化 的 
时 候 被 读 取 到 。 为 了 提供 一 个 动态 的 行为 ， 需 要 暴露 出 一 些 合适 的 getter 与 setter 方 法 。 下 面 
的 代码 演示 了 如 何 使 用 这 个 技巧 : 


public boolean isShowText() { 
return mShowText; 


} 


public void setShowText(boolean showText) { 
mShowText = showText; 
invalidate(); 
requestLayout(); 


请 注意 ， 在 setShowText 方 法 里 面 有 调用 invalidate()) and requestLayout()). 这 两 个 调用 是 确 
保 稳定 运行 的 关键 。 当 view 的 某 些 内 容 发 生变 化 的 时 候 ， 需 要 调用 invalidate 来 通知 系统 对 这 
个 view 进 行 redraw， 当 某 些 元 素 变化 会 引起 组 件 大 小 变化 时 ， 需 要 调用 requestLayout 方 法 。 
调用 时 若 忘 了 这 两 个 方法 ， 将 会 导致 hard-to-find bugs ° 


自 定义 的 view 也 需要 能 够 支持 响应 事件 的 监听 器 。 例 如 ， Piechart 暴露 了 一 个 自 定义 的 事 
fF oncurrentitemChanged 来 通知 监听 器 ， 用 户 已 经 切换 了 焦点 到 一 个 新 的 组 件 上 。 


我 们 很 容易 忘记 了 暴露 属性 与 事件 ， 特 别 是 当 你 
来 仔细 定义 你 的 view 的 交互 。 一 个 好 的 规则 是 总 


个 view 的 唯一 用 户 时 。 请 花费 一 些 时 间 


是 这 
是 暴露 任何 属性 与 事件 。 


设计 可 访问 性 


自 定义 vieW 应 该 支持 广泛 的 用 户 群 体 ， 一 些 不 能 看 到 或 使 用 触 屏 的 残障 人 士 。 为 了 支持 
残障 人 士 ， 我 们 应 该 : 


e 使 用 android:contentDescription 属性 标记 输入 字段 。 
e 在 适当 的 时 候 通 过 调用 sendAccessibilityEvent() 发 送 访问 事件 。 
e 支持 备用 控制 器 ， 如 方向 键 (D-pad) 和 轨迹 球 (trackball) 等 


对 于 创建 使 用 的 views 的 更 多 消息 , 请 参见 Android Developers Guide 中 的 Making 
Applications Accessible ° 


# 实现 自 定 义 View 的 绘制 
编写 :kesenhoo - 原文 :http://developer.android.com/training/custom-view/custom- 
draw.html 

自 定 义 view 的 最 重要 的 一 个 部 分 


分 是 自 定义 它 的 外 观 。 根 据 你 的 程序 的 需求 ， 自 定义 绘制 可 能 
简单 也 可 能 很 复杂 。 这 节 课 会 演示 一 些 最 党 


一 些 最 常见 的 操作 。 


Override onDraw() 


重 绘 一 个 自 定义 的 view 的 最 重要 的 步骤 是 重 写 onDraw() 方 法 。onDraw() 的 参数 是 一 个 Canvas 
对 象 。Canvas 类 定义 了 绘制 文本 ， 线 条 ， 图 像 与 许多 其 他 图 形 的 方法 。 你 可 以 在 onDraw 方 法 
里 面 使 用 那些 方法 来 创建 你 的 Ul。 


在 你 调用 任何 绘制 方法 之 前 ， 你 需要 创建 一 个 Paint 对 象 。 


创建 绘图 对 象 


android.graphics framework 把 绘制 定义 为 下 面 两 类 : 


e 绘制 什么 ， 由 Canvas 处 理 
e 如 何 绘制 ， 由 Paint 处 理 


例如 Canvas 提 供 绘制 一 条 直线 的 方法 ，Paint 提 供 直线 颜色 。Canvas 提 供 绘制 矩形 的 方法 ， 
Paint 定 义 是 否 使 用 颜色 填充 。 简 单 来 说 : Canvas € 3 T E E Eg 9 ERU > mPaintz LA 
色 ， 样 式 ， 字 体 ， 


所 以 在 绘制 之 前 ， 你 需要 创建 一 个 或 者 多 个 Paint 对 象 。 在 这 个 PieChart 的 例子 ， 是 
在 init() 方法 实现 的 ， 由 constructor 调 用 。 


private void init() { 
mTextPaint - new Paint(Paint.ANTI ALIAS FLAG); 
mTextPaint.setColor(mTextColor); 
if (mTextHeight == 0) { 
mTextHeight = mTextPaint.getTextSize(); 
y else { 
mTextPaint.setTextSize(mTextHeight); 


j 


mPiePaint - new Paint(Paint.ANTI ALIAS FLAG); 
mPiePaint.setStyle(Paint.Style.FILL); 
mPiePaint.setTextSize(mTextHeight); 


mShadowPaint = new Paint(0); 
mShadowPaint.setColor(0xff101010); 
mShadowPaint.setMaskFilter(new BlurMaskFilter(8, BlurMaskFilter.Blur.NORMAL)); 


刚 开 始 就 创建 对 象 是 一 个 重要 的 优化 技巧 。Views 会 被 频繁 的 重新 绘制 ， 初 始 化 许多 绘制 对 象 
需要 花费 兄 贵 的 代价 。 在 onDraw 方 法 里 面 创建 绘制 对 象 会 严重 影响 到 性 能 并 使 得 你 的 UI 显 得 
TH 


处 理 布局 事件 


为 了 正确 的 绘制 你 的 view， 你 需要 知道 View 的 大 小 。 复 杂 的 自 定义 view 通 常 需要 根据 在 屏幕 
上 的 大 小 与 形状 执行 多 次 layout 计 算 。 而 不 是 假设 这 个 view 在 屏幕 上 的 显示 大 小 。 即 使 只 有 一 
个 程序 会 使 用 你 的 view， 仍 然 是 需要 处 理 屏 幕 大 小 不 同 ， 密 度 不 同 ， 方 向 不 同 所 带 来 的 影 

响 。 

尽管 view 有 许多 方法 是 用 来 计算 大 小 的 ， 但 是 大 多 数 是 不 需要 重 写 的 。 如 果 你 的 View 不 需要 
特别 的 控制 它 的 大 小 ， 唯 一 需要 重 写 的 方法 是 onSizeChanged()). 

onSizeChanged()， 当 你 的 view 第 一 次 被 赋予 一 个 大 小 时 ， 或 者 你 的 view 大 小 被 更 改 时 会 被 执 
行 。 在 onSizeChanged 方 法 里 面 计算 位 置 ， 间 距 等 其 他 与 你 的 view 大 小 值 。 


当 你 的 view 被 设置 大 小 时 ，layout manager( 布 局 管理 器 ) 假 定 这 个 大 小 包括 所 有 的 view 的 内 边 
距 (padding)。 当 你 计算 你 的 view 大 小 时 ， 你 必须 处 理 内 边 距 的 值 。 这 
段 piechart.onsizechanged() 中 的 代码 演示 该 怎么 做 : 


// Account for padding 
(float)(getPaddingLeft() + getPaddingRight()); 
(float)(getPaddingTop() + getPaddingBottom()); 


float xpad 
float ypad 


// Account for the label 
if (mShowText) xpad += mTextWidth; 


float ww 
float hh 


(float)w - xpad; 
(float)h - ypad; 


// Figure out how big we can make the pie. 
float diameter - Math.min(ww, hh); 


如 果 你 想 更 加 精确 的 控制 你 的 view 的 大 小 ， 。 这 个 方法 的 参数 是 
View.MeasureSpec， 它 会 告诉 你 的 view 的 父 控 件 的 大 小 。 那 些 值 被 包装 成 int 类 型 ， 你 可 以 使 
用 静态 方法 来 获取 其 中 的 信息 。 


这 里 是 一 个 实现 onMeasure() 的 例子 。 在 这 个 例子 中 piechart 试 着 使 它 的 区 域 足够 大 ， 使 pie 
可 以 像 它 的 label 一 样 大 : 


@Override 

protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec) { 
// Try for a width based on our minimum 
int minw = getPaddingLeft() + getPaddingRight() + getSuggestedMinimumwidth(); 
int w = resolveSizeAndState(minw, widthMeasureSpec, 1); 


// Whatever the width ends up being, ask for a height that would let the pie 
// get as big as it can 
int minh = MeasureSpec.getSize(w) - (int)mTextWidth + getPaddingBottom() + getPaddi 


ngTop(); 
int h = resolveSizeAndState(MeasureSpec.getSize(w) - (int)mTextWidth, heightMeasure 
Spec, ©); 


setMeasuredDimension(w, h); 


上 面 的 代码 有 三 个 重要 的 事情 需要 注意 : 


e. 计算 的 过 程 有 把 view 的 padding 考 虑 进去 。 这 个 在 后 面 会 提 到 ， 这 部 分 是 view 所 控制 的 。 

e 帮助 方法 resolveSizeAndState() 是 用 来 创建 最 终 的 宽 高 值 的 。 这 个 方法 比较 view 的 期 户 
值 与 传递 给 onMeasure 方法 的 spec 值 ， 然 后 返回 一 个 合适 的 View.MeasureSpec 值 。 

e onMeasure() 没 有 返回 值 。 o n se es 。 调 用 这 个 
法 是 强制 执行 的 ， 如 果 你 遗漏 了 这 个 方法 ， 会 出 现 运行 时 异常 


A 
绘图 ! 


每 个 view 的 onDraw 都 是 不 同 的 ， 但 是 有 下 面 一 些 常见 的 操作 : 


e 绘制 文字 使 用 drawText()。 指 定 字体 通过 调用 setTypeface(), 通过 setColor() 来 设置 文字 闫 
&. 

e 绘制 基本 图 形 使 用 drawRect(), drawOval(), drawArc(). 通过 setStyle() 来 指定 形状 是 否 
要 filled, outlined. 

e 绘制 一 些 复杂 的 图 形 ， 使 用 Path 类 . 通过 给 Path 对 象 添加 直线 与 曲线 , 然后 使 用 
drawPath() 来 绘制 图 形 . 和 基本 图 形 一 样 ，paths 也 可 以 通过 setStyle 来 设置 是 outlined， 
filled, both. 

e 通过 创建 LinearGradient 对 象 来 定义 渐变 。 调 用 setShader() 来 使 用 LinearGradient 。 

e 通过 使 用 drawBitmap 来 绘制 图 片 . 


protected void onDraw(Canvas canvas) { 
super.onDraw(canvas); 


// Draw the shadow 

canvas.drawOval( 
mShadowBounds, 
mShadowPaint 


); 
// Draw the label text 


canvas.drawText(mData.get(mCurrentItem).mLabel, mTextX, mTextY, mTextPaint); 


for (int i = 0; i < mData.size(); ++i) { 
Item it = mData.get(i); 
mPiePaint.setShader(it.mShader); 
canvas.drawArc(mBounds, 
360 - it.mEndAngle, 
it.mEndAngle - it.mStartAngle, 
true, mPiePaint); 


// Draw the pointer 
canvas.drawLine(mTextX, mPointerY, mPointerX, mPointerY, mTextPaint); 
canvas.drawCircle(mPointerX, mPointerY, mPointerSize, mTextPaint); 


# 使 得 View 可 交互 


编写 :kesenhoo - 原文 :http://developer.android.com/training/custom-view/make- 
interactive.html 


绘制 Ul 仅仅 是 创建 自 定 义 View 的 一 部 分 。 你 还 需要 使 得 你 的 View 能 够 以 模拟 现实 世界 的 方式 
来 进行 反馈 。 对 象 应 该 总 是 与 现实 情景 能 够 保持 一 致 。 例 如 ， 图 片 不 应 该 突然 消失 又 从 另外 
一 个 地 方 出 现 ， 因 为 在 现实 世界 里 面 不 会 发 生 那 样 的 事情 。 正 确 的 应 该 是 ， 图 片 从 一 个 地 方 
移动 到 另外 一 个 地 方 。 


用 户 应 该 可 以 感受 到 UI 上 的 微小 变化 ， 并 对 模仿 现实 世界 的 细微 之 处 反应 强烈 。 例 如 ， 当 用 
户 fing( 迅 速 滑动 ) 一 个 对 象 时 ， 应 该 在 开始 时 感到 摩擦 带 来 的 阻力 ， 在 结束 时 感到 fing 带 动 的 
动力 。 应 该 在 滑动 开始 与 结束 的 时 候 给 用 户 一 定 的 反馈 。 


这 节 课 会 演示 如 何 使 用 Android framework 的 功能 来 为 自 定义 的 View 添 加 那些 现实 世界 中 的 行 
为 


o 


处 理 输 入 的 手势 


像 许 多 其 他 UI 框架 一 样 ，Android 提 供 一 个 输入 事件 模型 。 用 户 的 动作 会 转换 成 触发 一 些 回 调 
函数 的 事件 ， 你 可 以 重 写 这 些 回调 方法 来 定制 你 的 程序 应 该 如 何 响应 用 户 的 输入 事件 。 在 
Android 中 最 常用 的 输入 事件 是 touch， 它 会 触发 onTouchEvent(android.view.MotionEvent)) 的 
回调 。 重 写 这 个 方法 来 处 理 touch 事 件 : 


@Override 
public boolean onTouchEvent(MotionEvent event) { 
return super.onTouchEvent (event); 


} 


Touch 事 件 本 身 并 不 是 特别 有 用 。 如 今 的 touch Ul 定义 了 touch 事 件 之 间 的 相互 作用 ， 叫 做 
gestures。 例 如 tapping,pulling,flinging 与 Zooming。 为 了 把 那些 touch 的 源 事件 转换 成 
gestures, Android 提 供 了 GestureDetector 。 


通过 传 入 GestureDetectorOnGestureListener 的 一 个 实例 构建 一 个 GestureDetector。 如 果 你 
只 是 想 要 处 理 几 种 gestures( 手 势 操作 ) 你 可 以 继 

承 GestureDetector.SimpleOnGestureListener， 而 不 用 实现 
GestureDetector.OnGestureListener 接 口 。 例 如 ， 下 面 的 代码 创建 一 个 继 

承 GestureDetector.SimpleOnGestureListener 的 类 ， 并 重 写 onDown(MotionEvent))。 


class mListener extends GestureDetector.SimpleOnGestureListener { 
@Override 
public boolean onDown(MotionEvent e) { 
return true; 
j 
} 


mDetector = new GestureDetector(PieChart.this.getContext(), new mListener()); 


TE «1t GestureDetector.SimpleOnGestureListener, 你 必须 总 是 实现 onDown() 方 法 ， 
并 返回 true。 这 一 步 是 必须 的 ， 因 为 所 有 的 gestures 都 是 从 onDown() 开 始 的 。 如 果 你 在 
onDown() 里 面 返回 false， 系 统 会 认为 你 想 要 忽略 后 续 的 gesture, 那 么 
GestureDetector.OnGestureListener 的 其 他 回调 方法 就 不 会 被 执行 到 了 。 一 旦 你 实现 了 
GestureDetector.OnGestureListener 并 且 创 建 了 GestureDetector 的 实例 , 你 可 以 使 用 你 的 
GestureDetector 来 中 止 你 在 onTouchEvent 里 面 收 到 的 touch 事 件 。 


@Override 
public boolean onTouchEvent(MotionEvent event) { 
boolean result = mDetector.onTouchEvent(event) ; 
if (!result) { 
if (event.getAction() == MotionEvent.ACTION UP) { 
stopScrolling(); 
result = true; 


j 
} 


return result; 


当 你 传递 一 个 touch 事 件 到 onTouchEvent() 时 ， 若 这 个 事件 没有 被 辨认 出 是 何 种 gesture， 它 会 
返回 false。 你 可 以 执行 自 ecu A o 


基本 合理 的 物理 运 元 


Gestures 是 控制 触摸 设备 的 一 种 强 有 力 的 方式 ， 但 是 除非 你 能 够 产 出 一 个 合理 的 触摸 反馈 ， 

否则 将 是 违反 用 户 直 觉 的 。 一 个 很 好 的 例子 是 fing 手 势 ， 用 户 迅 速 的 在 屏幕 上 移动 手指 然后 抬 
手 离开 屏幕 。 这 个 手势 应 该 使 得 UI 迅速 的 按照 fing 的 方向 进行 滑动 ， 然 后 慢 慢 停 下 来 ， 就 像 是 
用 户 旋转 一 个 飞轮 一 样 。 


但 是 模拟 这 个 飞轮 的 感觉 并 不 简单 ， 要 想得到 正确 的 飞轮 模型 ， 需 要 大 量 的 物理 ， 数 学 知 
识 。 幸 运 的 是 ，Android 有 提供 帮助 类 来 模拟 这 些 物 理 行 为 。Scroller 是 控制 飞轮 式 的 fing 的 基 


Xo 


要 启动 一 个 fling， 需 调用 fling() ， 并 传 入 启动 速 举 、x、y 的 最 小 值 和 最 大 值 ， 对 于 启动 速度 
值 ， 可 以 使 用 GestureDetector 计 算得 出 。 


@Override 
public boolean onFling(MotionEvent e1, MotionEvent e2, float velocityX, float velocity 
XO 

mScroller.fling(currentX, currentY, velocityX / SCALE, velocityY / SCALE, minX, min 
Y, maxX, maxY); 

postInvalidate(); 


Note: 尽管 速率 是 通过 GestureDetector 来 计算 的 ， 许 多 开发 者 感觉 使 用 这 个 值 使 得 fing 
动画 太 快 。 通 常 把 Xx 与 y 设 置 为 4 到 8 倍 的 关系 。 


调用 fling()) 时 会 为 fling 手 势 设 置物 理 模 型 。 然 后 ， 通 过 调用 定期 调用 
Scroller.computeScrollOffset()) 来 更 新 Scroller。computeScrollOffset()) 通 过 读 取 当 前 时 间 和 
使 用 物理 模型 来 计算 x 和 yy 的 位 置 更 新 Scroller 对 象 的 内 部 状态 。 调 用 getCurrX()) 和 getCurrY()) 
来 获取 这 些 值 。 


大 多 数 view 通 过 Scroller 对 象 的 x,y 的 位 置 直接 到 scrollTo())，PieChart 例 子 稍 有 不 同 ， 它 使 用 当 
前 滚动 y 的 位 置 设置 图 表 的 旋转 角度 。 


if (!mScroller.isFinished()) { 
mScroller.computeScrollOffset(); 
setPieRotation(mScroller.getCurrY()); 


Scroller 类 会 为 你 计算 滚动 位 置 ， 但 是 他 不 会 自动 把 哪些 位 置 运 用 到 你 的 view 上 面 。 你 有 责任 
确保 View 获 取 并 运用 到 新 的 坐标 。 你 有 两 种 方法 来 实现 这 件 事情 


e 在 调用 fling() 之 后 执行 postinvalidate(), 这 是 为 了 确保 能 强制 进行 重 画 。 这 个 技术 需要 每 次 
在 onDraw 里 面 计 算 过 scroll offsets( 滚 动 偏 移 量 ) 之 后 调用 postlnvalidate()。 

e 使 用 ValueAnimator 在 fling 是 展现 动画 ， 并 且 通 过 调用 addUpdateListener() 增 加 对 fing 过 
程 的 监听 。 


这 个 PieChart 的 例子 使 用 了 第 二 种 方法 。 这 个 方法 使 用 起 来 会 稍微 复杂 一 点 ， 但 是 它 更 有 效 
率 并 且 避 免 了 不 必要 的 重 画 的 view 进 行 重 绘 。 缺 点 是 ValueAnimator 是 从 API Level 11 才 有 
的 。 因 此 他 不 能 运用 到 3.0 的 系统 之 前 的 版 本 上 。 


Note: ValueAnimator 虽 然 是 API 11 才 有 的 ， 但 是 你 还 是 可 以 在 最 低 版 本 低 于 3.0 的 系统 上 
使 用 它 ， 做 法 是 在 运行 时 判断 当前 的 API Level， 如 果 低 于 11 则 跳 过 。 


mScroller = new Scroller(getContext(), null, true); 
mScrollAnimator - ValueAnimator.ofFloat(0,1); 
mScrollAnimator.addUpdateListener(new ValueAnimator.AnimatorUpdateListener() 1 
@Override 
public void onAnimationUpdate(ValueAnimator valueAnimator) { 
if (!mScroller.isFinished()) { 
mScroller.computeScrollOffset(); 
setPieRotation(mScroller.getCurrY()); 
else { 
mScrollAnimator.cancel(); 
onScrollFinished(); 


3); 


RRP 


用 户 期 待 一 个 Ul 之 间 的 切换 是 能 够 平滑 过 渡 的 。U| 元 素 需 要 做 到 渐 入 淡出 来 取代 突然 出 现 与 
消失 。Android 从 3.0 开 始 有 提供 property animation framework, 用 来 使 得 平滑 过 渡 变 得 更 加 容 


易 。 


使 用 这 套 动 画 系统 时 ， 任 何 时候 属 性 的 改变 都 会 影响 到 你 的 视图 ， 所 以 不 要 直接 改变 属性 的 

值 。 而 是 使 用 ValueAnimator 来 实现 改变 。 在 下 面 的 例子 中 ， 在 PieChart 中 更 改选 择 的 部 分 将 
导致 整个 图 表 的 旋转 ， 以 至 选择 的 进入 选择 区 内 。ValueAnimator 在 数 百 毫秒 内 改变 旋转 量 ， 

而 不 是 突然 地 设置 新 的 旋转 值 。 


mAutoCenterAnimator = ObjectAnimator.ofInt(PieChart.this, "PieRotation", 0); 
mAutoCenterAnimator.setIntValues(targetAngle); 
mAutoCenterAnimator.setDuration(AUTOCENTER ANIM DURATION); 
mAutoCenterAnimator.start(); 


如 果 你 想 改 变 的 是 view 的 某 些 基础 属性 ， 你 可 以 使 用 ViewPropertyAnimator , 它 能 够 同时 执行 
多 个 属性 的 动画 。 


animate().rotation(targetAngle).setDuration(ANIM DURATION).start(); 


# 优化 自 定 义 View 


编写 :kesenhoo - 原文 :http://developer.android.com/training/custom-views/optimizing- 
view.html 


前 面 的 课程 学 习 到 了 如 何 创建 设计 良好 的 View， 并 且 能 够 使 之 在 手势 与 状态 切换 时 得 到 正确 
的 反馈 。 下 面 要 介绍 的 是 如 何 使 得 view 能 够 执行 更 快 。 为 了 避免 Ul 显 得 卡 顿 ， 你 必须 确保 动 
画 能 够 保持 在 60fps 。 


Do Less, Less Frequently 


为 了 加 速 你 的 view， 对 于 频繁 调用 的 方法 ， 需 要 尽量 减少 不 必要 的 代码 。 先 从 onDraw 开 始 ， 
需要 特别 注意 不 应 该 在 这 里 做 内 存 分 配 的 事情 ， 因 为 它 会 导致 GC， 从 而 导致 卡 顿 。 在 初始 化 
或 者 动画 间隙 期 间 做 分 配 内 存 的 动作 。 不 要 在 动画 正在 执行 的 时 候 做 内 存 分 配 的 事情 。 


你 还 需要 尽 可 能 的 减少 onDraw 被 调用 的 次 数 ， 大 多 数 时 候 导 致 onDraw 都 是 因为 调用 了 
invalidate(). 因 此 请 尽量 减少 调用 invaildate() 的 次 数 。 如 果 可 能 的 话 ， 尽 量 调用 含有 4 个 参数 的 
invalidate() 方 法 而 不 是 没有 参数 的 invalidate()。 没 有 参数 的 invalidate 会 强制 重 绘 整个 view ° 


另外 一 个 非常 耗 时 的 操作 是 请 求 layout。 任 何 时 候 执行 requestLayout()， 会 使 得 Android UI A 
统 去 遍历 整个 View 的 层级 来 计算 出 每 一 个 view 的 大 小 。 如 果 找 到 有 冲突 的 值 ， 它 会 需要 重新 
计算 好 几 次 。 另 外 需要 尽量 保持 View 的 层级 是 扁平 化 的 ， 这 样 对 提高 效率 很 有 帮助 。 


如 果 你 有 一 个 复杂 的 Ul， 你 应 该 考虑 写 一 个 自 定义 的 ViewGroup 来 执行 他 的 layout 操 作 。 与 内 
置 的 view 不 同 ， 自 定义 的 view 可 以 使 得 程序 仅仅 测量 这 一 部 分 ， 这 避免 了 遍历 整个 view 的 层 
级 结构 来 计算 大 小 。 这 个 PieChart 例子 展示 了 如 何 继承 ViewGroup 作 为 自 定义 view 的 一 部 

分 。PieChart 有 子 views， 但 是 它 从 来 不 测量 它们 。 而 是 根据 他 自身 的 layout 法 则 ， 直 接 设置 
它们 的 大 小 。 


使 用 硬件 加 速 


从 Android 3.0 开 始 ，Android 的 2D 图 像 系统 可 以 通过 GPU (Graphics Processing Unit)) 来 加 
速 。GPU 硬 件 加 速 可 以 提高 许多 程序 的 性 能 。 但 是 这 并 不 是 说 它 适 合 所 有 的 程序 。Android 
framework 让 你 能 过 随意 控制 你 的 程序 的 各 个 部 分 是 否 启 用 硬件 加 速 。 


参考 Android Developers Guide 中 的 Hardware Acceleration 来 学 习 如 何在 application， 
activity, 或 window 层 启 用 加 速 。 注 意 除 了 Android Guide 的 指导 之 外 ， 你 必须 要 设置 你 的 应 
用 的 target API 为 11， 或 更 高 ， 通 过 在 你 的 AndroidManifest.xml 文件 中 增加 < uses-sdk 
android:targetSdkVersion="11"/> 。 


一 旦 你 开启 了 硬件 加 速 ， 性 能 的 提示 并 不 一 定 可 以 明显 察觉 到 。 移 动 设备 的 GPU 在 某 些 例如 
scaling,rotating 与 translating 的 操作 中 表现 良好 。 但 是 对 其 他 一 些 任务 ， 比 如 画 直 线 或 曲线 ， 

则 表现 不 佳 。 为 了 充分 发 挥 GPU 加 速 ， 你 应 该 最 大 化 GPU 擅 长 的 操作 的 数量 ， 最 小 化 GPU 不 
擅长 操作 的 数量 。 


在 下 面 的 例子 中 ， 绘 制 pie 是 相对 来 说 比较 费时 的 。 解 决 方案 是 把 pie 放 到 一 个 子 view 中 ， 并 设 
置 View 使 用 LAYER_TYPE_HARDWARE 来 进行 加 速 。 


private class PieView extends View { 


public PieView(Context context) { 
super(context); 
if (!isInEditMode()) { 
setLayerType(View.LAYER TYPE HARDWARE, null); 
} 
} 


@Override 
protected void onDraw(Canvas canvas) { 
super .onDraw(canvas); 


for (Item it : mData) { 
mPiePaint.setShader(it.mShader); 
canvas.drawArc(mBounds, 
360 - it.mEndAngle, 
it.mEndAngle - it.mStartAngle, 
true, mPiePaint); 


j 


@Override 
protected void onSizeChanged(int w, int h, int oldw, int oldh) { 
mBounds = new RectF(0, 0, w, h); 


j 


RectF mBounds; 


通过 这 样 的 修改 以 后 ，PieChart.PieView.onDraw() 只 会 在 第 一 次 现实 的 时 候 被 调用 。 之 后 ， 
pie chart 会 被 缓存 为 一 张 图 片 ， 并 通过 GPU 来 进行 重 画 不 同 的 角度 。GPU 特 别 擅长 这 类 的 事 
情 ， 并 且 表 现 效 果 突 出 。 


缓存 图 片 到 hardware layer 会 消耗 video memory， 而 video memory 又 是 有 限 的 。 基 于 这 样 的 
考虑 ， 仅 仅 在 用 户 触发 scrolling 的 时 候 使 用 LAYER TYPE HARDWARE ， 在 其 他 时 候 ， 使 


用 LAYER TYPE NONE ? 


优化 自 定 义 View 
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创建 向 后 兼容 的 UI 


编写 :spencer198711 - 原文 :http://developer.android.com/training/backward-compatible- 
ui/index.html 


这 一 课 展示 了 如 何以 向 后 兼容 的 方式 使 用 在 新 版 本 的 Android 上 可 用 的 UI 组 件 和 API， 确 保 你 
的 应 用 在 之 前 的 版 本 上 依然 能 够 运行 。 


贯穿 整个 课程 ， 在 Android 3.0 被 新 引入 的 Action Bar Tabs 功 能 在 本 课程 中 作为 指导 例子 ， 但 
是 你 可 以 在 其 他 UI 组 件 和 API 功 能 上 运用 这 种 方式 。 


Sample 


http://developer.android.com/shareables/training/TabCompat.zip 


Lessons 


抽象 出 新 的 APls 


决定 你 的 应 用 需要 的 功能 和 接口 。 学 习 如 何 为 你 的 应 用 定义 面向 特定 应 用 的 、 作 为 中 间 
媒介 并 抽象 出 UI 组 件 具 体 实现 的 java 接 口 。 


e 代理 至 新 的 APls 

学 习 如 何 创 建 使 用 新 的 APls 的 接口 的 具体 实现 
e 使 用 昌 的 APls 实 现 新 API 的 效果 

学 习 如 何 创 建 使 用 老 的 APls 的 自 定义 的 接口 实现 
e 使 用 能 感知 版 本 的 组 件 


学 习 如 何在 运行 的 时 候 去 选择 一 个 具体 的 实现 ， 并 且 开 始 在 你 的 应 用 中 使 用 接口 。 


抽象 出 新 的 APls 


^h 5 :spencer198711 - 原文 :http://developer.android.com/training/backward-compatible- 
ui/abstracting.html 


假如 你 想 使 用 Action Bar Tabs 作 为 你 的 应 用 的 顶层 导航 的 主要 形式 。 不 幸 的 是 ，ActionBar 
APls 只 在 Android 3.0 (API 等 级 11) 之 后 才能 使 用 。 因 此 ， 如 果 你 想 要 在 运行 之 前 版 本 的 
Android 平 台 的 设备 上 分 发 你 的 应 用 ， 你 需要 提供 一 个 支持 新 的 API 的 实现 ， 同 时 提供 一 个 回 
退 机 制 ， 使 得 能 够 使 用 旧 的 APls。 


在 本 课程 中 ， 使 用 了 具有 面向 特定 版 本 实现 的 抽象 类 去 构建 一 个 tab 页 形式 的 用 户 界 面 ， 并 以 
此 提供 向 后 兼容 性 。 这 一 课 描 述 了 如 何 为 新 的 tab API 创 建 一 个 抽象 层 ， 并 以 此 作为 构建 tab 组 
件 的 第 一 步 。 


为 抽象 做 准备 


在 Java 编 程 语言 中 ， 抽 象 包 Ce ns li 在 
新 版 本 的 Android API 的 情况 中 ， 你 可 以 使 用 抽象 去 构建 能 感知 版 本 的 组 件 ， 这 个 组 件 会 在 新 
版 本 的 设备 上 使 用 当前 的 APls ， 当 回 退 到 老 的 设备 上 同时 存在 兼容 的 APls。 


当 使 用 这 种 方法 时 ， 你 首先 需要 决定 哪些 要 使 用 的 类 需要 提供 向 后 兼容 ， 然 后 去 根据 新 类 中 
pee 1 建 抽象 类 。 在 创建 抽象 接口 的 过 程 中 ， 你 应 该 尽 可 能 多 的 为 新 APls 创 建 镜 
像 。 这 会 最 大 化 前 向 兼容 性 ， 使 得 在 将 来 当 这 些 接口 不 再 需要 的 时 候 ， 废 齐 这 些 接口 会 更 加 
容易。 


在 为 新 的 APls 创 建 抽象 类 之 后 ， 任 何 数量 的 实现 都 可 以 在 运行 的 过 程 中 去 创建 和 选 Si 


fb o ete 05542 0 dur Mc 能 会 使 
用 最 新 发 布 的 APls， 而 其 他 的 则 会 去 使 用 比较 老 的 APls。 


创建 抽象 的 Tab 接 口 


为 了 能 够 创建 一 个 向 后 兼容 的 tabs， 你 首先 需要 决定 你 的 应 用 需要 哪些 功能 和 哪些 特定 的 
APls 接 口 。 在 顶层 分 节 tabs 的 情况 下 ， 假 设 你 有 以 下 功能 需求 

1. 显示 图 标 和 文本 的 Tab 指 示 器 

2. Tabs 可 以 跟 一 个 Fragment 实 例 向 关联 

3，Activity 可 以 监听 到 Tab 变 化 


提前 准备 这 些 需求 能 够 让 你 控制 抽象 层 的 范围 。 这 意味 着 你 可 以 花 更 少 的 时 间 去 创建 抽象 层 
的 多 个 具体 实现 ， 并 很 快 就 人 "e 文 些 新 的 后 向 兼容 的 实现 。 


Tabs 的 es Tab， 为 了 能 够 使 得 tab 能 够 感知 Android 版 本 ， 这 些 
是 需要 抽象 出 来 的 APIs。 这 个 示例 项 目的 需求 要 求 同 Eclair(API 等 级 5) 保 持 一 致 性 ， 同 时 能 够 
a 能 。 一 张 展示 能 够 支持 这 两 种 实现 的 类 结构 和 它们 

的 抽象 父 类 的 图 显示 如 下 : 


| — —1 CompatTabHoneycomb 
| CompatTab | CompatTab 一 一 











= | - CompatTabEc lair 


。 图 1. 抽 象 基 类 和 版 本 相关 的 子 类 实现 类 结构 图 


Abstract ActionBar.Tab 


通过 创建 一 个 代表 tab 的 抽象 类 来 开始 着 手 构 建 tab 抽 象 层 ， 这 个 类 是 Actionbar. Tab 接口 的 镜 
像 : 


public abstract class CompatTab ( 


public abstract CompatTab setText(int resId); 
public abstract CompatTab setIcon(int resId); 





public abstract CompatTab setTabListener ( 
CompatTabListener callback); 

public abstract CompatTab setFragment(Fragment fragment); 

public abstract CharSequence getText(); 

public abstract Drawable getIcon(); 

public abstract CompatTabListener getCallback(); 

public abstract Fragment getFragment(); 


在 这 里 ， 为 了 简化 诸如 tab 对 象 和 Activity 的 联系 (未 在 代码 片段 中 显示 ) 等 公共 的 功能 ， 
以 使 用 一 个 抽象 类 而 不 是 去 使 用 接口 。 


44 % Æ Action Bar Tab 的 方法 


下 一 步 ， 定 义 一 个 能 够 允许 你 往 Activity 中 创建 和 添加 tab 抽 象 类 ， 并 定义 类 
似 ActionBarnewTab()) 和 ActionBar.addTab()) 的 方法 。 





public abstract class TabHelper { 


public CompatTab newTab(String tag) { 
// This method is implemented in a later lesson. 


} 
public abstract void addTab(CompatTab tab); 


在 下 一 课程 中 ， 你 将 会 创建 TabHelper 和 CompatTab 的 实现 ， 它 能 够 在 新 旧 不 同 的 平台 版 本 上 
都 能 工作 。 


Oo 
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代理 至 新 的 APls 


编写 : spencer198711 - Æ xc:http;//developer.android.com/training/backward-compatible- 


ui/new-implementation.html 


这 一 课 展 示 了 如 何 编写 CompatTab 和 TabHelper 等 抽象 类 的 子 类 ， 并 且 使 用 了 较 新 的 APls。 你 
的 应 用 可 以 在 支持 这 些 新 的 APls 的 平台 版 本 的 设备 上 使 用 这 种 实现 方式 。 


使 用 较 新 的 APls 实 现 Tabs 


CompatTab 和 TabHelper 抽 象 类 的 具体 子 类 是 一 种 代理 实现 ， 它 们 使 用 了 使 用 较 新 的 APls。 由 
于 抽象 类 在 之 前 的 课程 中 定义 并 且 是 对 新 APls 接 口 (类 结构 、 方 法 签名 等 等 ) 的 镜像 ， 使 用 
新 APls 的 具体 子 类 只 是 简单 的 代理 方法 调用 和 方法 调用 的 结果 。 


你 可 以 在 这 些 具体 子 类 中 直接 使 用 较 新 的 APls， 由 于 使 用 延迟 类 加 载 的 方式 ， 在 早期 版 本 的 
设备 上 并 不 会 发 生 崩 演 现 象 。 这 些 类 在 首次 次 被 访问 (实例 化 类 对 象 或 者 访问 类 的 静态 属性 
或 静态 方法 ) 的 时 候 才 会 去 加 载 并 初始 化 。 因 此 ， 只 要 你 不 在 Honeycomb 之 前 的 设备 上 实例 
化 Honeycomb 相 关 的 实现 ，dalvik 虚 拟 机 都 不 会 抛 出 VerifyError 异 常 。 


对 于 本 实现 ， 一 个 比较 好 的 命名 约定 是 把 具体 子 类 需要 的 API 等 级 或 者 版 本 名 字 附 加 在 APls 接 
口 的 后 边 。 例 如 ， 本 地 tab 实 现 可 以 由 compatTabHoneycomb 和 abHelperHoneycomb 这 两 个 类 提 
供 ， 名 字 后 面 附加 Honeycomb 是 由 于 它们 都 依赖 于 Android 3.0 (API 等 级 11) 之 后 版 本 的 
APIs ° 


CompatTab = | CompatTabHoneycomb 








e 图 1. Honeycomb 上 tabs 实 现 的 类 关系 图 . 


实现 CompatTabHoneycomb 


CompatTabHoneycomb 是 CompatTab 抽 RR 的 具体 实现 并 用 来 引用 单独 的 
tabs ° compatTabHoneycomb 只 是 简单 的 代理 ActionBar.Tab 对 象 的 方法 调用 。 开始 使 用 
ActionBar.Tab 的 APls 实 现 CompatTabHoneycomb : 


public class CompatTabHoneycomb extends CompatTab { 
// The native tab object that this CompatTab acts as a proxy for. 
ActionBar.Tab mTab; 


protected CompatTabHoneycomb(FragmentActivity activity, String tag) { 


// Proxy to new ActionBar.newTab API 
mTab - activity.getActionBar().newTab(); 


} 
public CompatTab setText(int resId) { 


// Proxy to new ActionBar.Tab.setText API 
mTab.setText(resId); 
return this; 


// Do the same for other properties (icon, callback, etc.) 


实现 TabHelperHoneycomb 


TabHelperHoneycomb 是 TabHelper 抽象 类 的 具体 实现 ， TabHelperHoneycomb 代理 方法 调用 
到 ActionBar 对 象 ， 而 这 个 ActionBar 对 象 是 从 包含 他 的 Activity 中 获取 的 。 


实现 TabHelperHoneycomb ， 代 理 其 方法 调用 到 ActionBar 的 API : 


public class TabHelperHoneycomb extends TabHelper { 
ActionBar mActionBar; 


protected void setUp() { 
if (mActionBar == null) { 
mActionBar - mActivity.getActionBar(); 
mActionBar.setNavigationMode( 
ActionBar.NAVIGATION MODE TABS); 


public void addTab(CompatTab tab) { 


// Tab is a CompatTabHoneycomb instance, so its 
// native tab object is an ActionBar.Tab. 
mActionBar.addTab((ActionBar.Tab) tab.getTab()); 


// The other important method, newTab() is part of 
// the base implementation. 


代理 至 新 的 APls 
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使 用 昌 的 APls 实 现 新 API 的 效果 


编写 : spencer198711 - 原文 :http://developer.android.com/training/backward-compatible- 
ui/older-implementation.html 


这 一 课 讨 论 了 如 何 创 建 一 个 支持 旧 的 设备 并 且 与 新 的 APls 接 口 相同 的 实现 。 


决定 一 个 替代 方案 


在 以 向 后 兼容 的 方式 使 用 较 新 的 UI| 功 能 的 时 候 ， 最 具 挑 战 的 任务 是 为 上 昌 的 平台 版 本 决定 一 个 
解决 方案 。 在 很 多 情况 下 ， 使 用 昌 的 UI 框架 中 的 功能 是 有 可 能 完成 这 些 新 的 UI 组 件 的 。 例 
如 : 


Action Bar 可 以 使 用 水 平 的 包含 图 片 按 钮 的 LinearLayout 来 实现 ， 这 个 在 Activity 中 的 
LinearLayout 作 为 自 定义 标题 栏 或 者 仅仅 作为 视图 。 下 拉 功 能 行为 可 以 使 用 设备 的 菜单 按 
钮 来 实现 。 

Action Bar 的 tab 页 可 以 使 用 包含 按钮 的 水 平 的 LinearLayout， 或 者 使 用 TabWidgetUl 控 件 
来 实现 。 

e NumberPicker 和 Switch 控件 可 以 分 别 通过 使 用 Spinner 和 ToggleButton 榨 件 来 实现 。 

e ListPopupWindow 和 PopupMenu 控 件 可 以 通过 使 用 PopupWindow 来 实现 。 


为 了 往 老 的 设备 上 向 后 移植 Ul 组件 ， 这 些 一 般 不 是 一 刀 切 的 解决 方案 。 注 意 用 户 体验 : 在 老 
的 设备 上 ， 用 户 可 能 不 熟悉 新 的 界面 设计 模式 和 UI 组 件 ， 思 考 一 下 如 何 使 用 熟悉 的 控件 去 实 
现 相同 的 功能 。 在 很 多 种 情况 下 ， 这 些 通常 不 会 被 注意 到 ， 特 别 是 在 如 果 新 的 UI 组 件 在 应 用 
程序 的 生态 系统 中 是 突出 的 (比如 Action Bar) ， 或 者 交互 模型 是 非常 简单 和 直观 的 (比如 使 
用 ViewPager 去 滑动 界面 )。 


使 用 昌 的 APls 实 现 Tabs 


你 可 以 使 用 TabWidget 和 TabHost (尽管 其 中 一 个 也 可 以 使 用 水 平方 向 的 Button 控 件 ) 去 创建 
Action Bar Tabs 的 老 的 实现 。 可 以 在 TabHelperEclair 和 CompatTabEclair 的 类 中 去 实现 ， 因 为 
这 些 实现 使 用 了 不 迟 于 Android 2.0 (Eclair) 的 APls。 


CompatTab = | CompatTabEclair | 








e 图 1. Eclair 版 本 上 实现 tabs 的 类 图 


CompatTabEclair 在 实例 变量 中 保存 了 诸如 tab 文 本 和 tab 图 标 等 tab 属 性 ， 因 为 在 老 的 版 本 中 没 


有 ActionBarTab 对 象 去 处 理 这 些 数据 存储 。 


public class CompatTabEclair extends CompatTab { 
// Store these properties in the instance, 
// as there is no ActionBar.Tab object. 
private CharSequence mText; 


public CompatTab setText(int resId) { 
// Our older implementation simply stores this 
// information in the object instance. 
mText - mActivity.getResources().getText(resId); 
return this; 


// Do the same for other properties (icon, callback, etc.) 


TabHelperEclair 利用 了 TabHost 控 件 的 方法 去 创建 TabHost.TabSpec 对 象 和 tab 的 页 面 指示 效 
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public class TabHelperEclair extends TabHelper { 
private TabHost mTabHost; 


protected void setUp() { 
if (mTabHost -- null) ( 
// Our activity layout for pre-Honeycomb devices 
// must contain a TabHost. 
mTabHost - (TabHost) mActivity.findViewById( 
android.R.id.tabhost); 
mTabHost.setup(); 


public void addTab(CompatTab tab) { 


TabSpec spec - mTabHost 
.newTabSpec(tag) 
.setIndicator(tab.getText()); // And optional icon 


mTabHost.addTab( spec); 


// The other important method, newTab() is part of 
// the base implementation. 


现在 你 已 经 有 了 两 种 compatTab 和 TabHelper 的 实现 ， 一 种 是 使 用 了 新 的 APls 为 了 能 够 在 
Android 3.0 或 其 后 版 本 设备 上 能 够 运行 ， 另 一 种 则 是 使 用 了 四 的 APls 为 了 在 Android 2.0 或 之 
前 的 设备 上 能 够 运行 。 下 一 课 讨 论 在 应 用 中 使 用 这 两 种 实现 。 


使 用 能 感知 版 本 的 组 件 


^h 5 :spencer198711 - 原文 :http://developer.android.com/training/backward-compatible- 
ui/using-component.html 


既然 对 TabHelper 和 compatTab 你 已 经 有 了 两 种 具体 实现 ， 一 个 为 Android 3.0 和 其 后 版 本 ， 
一 个 为 Android 3.0 之 前 的 版 本 。 现 在 ， 该 使 用 这 些 实现 做 些 事情 了 。 这 一 课 讨 论 了 创建 在 这 
两 种 实现 之 前 切换 的 逻辑 ， 创 建 能 够 感知 版 本 的 界面 布局 ， 最 终 使 用 我 们 创建 的 后 向 兼容 的 
UI 组 件 。 


添加 切换 逻辑 


TabHelper 抽象 类 基于 当前 设备 的 平台 版 本 ， 是 用 来 创建 适当 版 本 
的 TabHelper 和 compatTab 实例 的 工厂 类 : 


public abstract class TabHelper ( 


// Usage is TabHelper.createInstance(activity) 
public static TabHelper createInstance(FragmentActivity activity) { 
if (Build.VERSION.SDK INT >= Build.VERSION CODES.HONEYCOMB) { 
return new TabHelperHoneycomb(activity); 
} else { 
return new TabHelperEclair(activity); 
} 
} 


// Usage is mTabHelper.newTab("tag") 
public CompatTab newTab(String tag) { 
if (Build.VERSION.SDK INT >= Build.VERSION CODES.HONEYCOMB) { 
return new CompatTabHoneycomb(mActivity, tag); 
} else { 
return new CompatTabEclair(mActivity, tag); 


} 


创建 能 感知 版 本 的 Activity 布 局 


下 一 步 是 提供 能 够 支持 两 种 tab 实 现 的 Activity 界 面 布 局 。 对 于 老 的 实现 (TabHelperEclair) ， 
你 需要 确保 你 的 界面 布局 包含 TabWidget 和 TabHost， 同 时 存在 一 个 包含 tab 内 容 的 布局 容器 。 


res/layout/main.xml: 


<!-- This layout is for API level 5-10 only. --> 

«TabHost xmlns:android-"http://schemas.android.com/apk/res/android" 
android:id-"Qandroid:id/tabhost" 
android: layout_width="match_parent" 
android: layout_height="match_parent"> 


<LinearLayout 
android:orientation="vertical" 
android: layout_width="match_parent" 
android: layout_height="match_parent" 
android: padding="5dp"> 


<TabWidget 
android:id="@android:id/tabs" 
android: layout_width="match_parent" 
android: layout_height="wrap_content" /> 


<FrameLayout 
android: id="@android:id/tabcontent" 
android: layout_width="match_parent" 
android: layout_height="Odp" 
android: layout_weight="1" /> 


</LinearLayout> 
</TabHost> 


对 于 rabHelperHoneycomb 的 实现 ， 你 唯一 要 做 的 就 是 一 个 包含 tab 内 容 的 FrameLayout， 这 是 
由 于 ActionBar 已 经 提供 了 tab 相 关 的 页 面 。 


res/layout-v11/main.xml: 


«FrameLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:id-"Qandroid:id/tabcontent" 
android: layout_width="match_parent" 
android: layout_height="match_parent" /> 


在 运行 的 时 候 ，Android 将 会 根据 平台 版 本 去 决定 使 用 哪个 版 本 的 main.xml 布局 文件 。 这 根 上 
一 节 中 选择 哪 一 个 版 本 的 TabHelper 所 展示 的 逻辑 是 相同 的 。 


在 Activity 中 使 用 TabHelper 


在 Activity 的 onCreate()) 方 法 中 ， 你 可 以 获得 一 个 TabHelper 对 象 ， 并 且 使 用 以 下 代码 添加 
tabs : 


@Override 
public void onCreate(Bundle savedInstanceState) { 
setContentView(R.layout.main); 


TabHelper tabHelper = TabHelper.createInstance(this); 
tabHelper.setUp(); 


CompatTab photosTab - tabHelper 
.DhewTab( "photos") 
.setText(R.string.tab photos); 

tabHelper.addTab(photosTab); 


CompatTab videosTab - tabHelper 
.DhewTab(" videos") 
.setText(R.string.tab videos); 

tabHelper.addTab(videosTab); 


当 和 运行 这 个 应 用 的 时 候 ， 代 码 会 自动 显示 对 应 的 界面 布局 和 实例 化 对 应 
的 TabHelperHoneycomb 或 TabHelperEclair 对 象 ， 而 实际 使 用 的 类 对 于 Actvity 来 说 是 不 透明 
的 ， 因 为 它们 拥有 共同 的 TabHelper 接口 。 


以 下 是 这 种 实现 运行 在 Android 2.3 和 Android 4.0 上 的 界面 截图 : 


使 用 版 本 敏感 的 组 件 
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e 图 1. 向 后 兼容 的 tabs 运 行 在 Android 2.37% &- E. (4% TabHelperEclair) 和 运行 在 Android 
4.0 设 备 上 的 截图 


实现 辅助 功能 


编写 :KOST - Æ x-:http;//developer.android.com/training/accessibility/index.html 
当 我 们 需要 尽 可 能 扩大 我 们 用 户 的 基数 的 时 候 ， 就 要 开始 注意 我 们 软件 的 可 达 性 了 
(Accessibility 易 接 近 ， 可 亲 性 )。 在 界面 中 展示 提示 对 大 多 数 用 户 而 言 是 可 行 的 ， 比 如 说 当 按 
钮 被 按 下 时 视觉 上 的 变化 ， 但 是 对 于 那些 视力 上 有 些 缺 陷 的 用 户 而 言 效果 就 不 是 那么 理想 
了 。 
本 章 将 给 您 演示 如 何 最 大 化 利用 Android 框 架 中 的 Accessibility 特 性 。 包 括 如 何 利 用 焦点 导航 
(focus navigation) 与 内 容 描述 (content description) 对 你 的 应 用 的 可 达 性 进行 优化 。 也 包括 了 
创建 Accessibility Service ， 使 用 户 与 应 用 (不 仅仅 是 你 自己 的 应 用 ) 之 间 的 交互 更 加 容易 。 


Lessons 


e 开发 Accessibility 应 用 


学 习 如 何 让 你 的 程序 更 易 用 ， 具 有 可 达 性 。 允许 使 用 键盘 或 者 十 字 键 (directional paa) 来 
进行 导航 ， 利 用 Accessibility Service 特 性 设置 标签 或 执行 事件 来 打造 更 舒适 的 用 户 体 


e 编写 Accessibility Services 


编写 一 个 Accessibility Service 来 监听 可 达 性 事件 ， 利 用 这 些 不 同类 型 的 事件 和 内 容 描 述 
来 帮助 用 户 与 应 用 的 交互 。 本 例 将 会 实现 利用 一 个 TTS 引 警 来 向 用 户 发 出 语音 提示 的 功 


AG 
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开发 辅助 程序 


编写 :KOST - 原文 :http://developer.android.com/training/accessibility/accessible- 
app.html 


本 课程 将 教 您 : 
1. 添加 内 容 描述 (Content Descriptions) 
2. 设计 焦点 导航 (Focus Navigation ) 
3. 触发 可 达 性 事件 (Accessibility Events) 
4. 测试 你 的 程序 


Android 平 台 本 身 有 一 些 专注 可 达 性 的 特性 ， 这 些 特性 可 以 帮助 你 专门 为 那些 视觉 上 或 生理 上 
有 缺陷 的 用 户 在 应 用 上 做 特别 的 优化 。 然 而 ， 正 确 的 优化 方式 或 最 简单 利用 这 个 特性 的 方法 
往往 不 是 那么 显而易见 的 。 本 课程 将 给 您 演示 如 何 利 用 和 实现 这 些 策略 和 平台 的 特性 功能 ， 
构建 一 个 更 友好 的 具有 可 达 性 的 Android 应 用 。 


添加 内 容 描述 


一 个 好 的 交互 界面 上 的 元 素 通 常 不 需要 特别 使 用 一 个 标签 来 表明 这 个 元 素 的 作用 。 例 如 对 于 
一 个 任务 型 应 用 来 说 ， 一 个 项 目 雳 边 的 义 选 框 表 达 的 意思 就 非常 明确 ， 或 者 对 于 一 个 文件 管 
理应 用 ， 垃 圾 桶 的 图 标 表达 的 意思 也 非常 清除 。 然 而 对 于 具有 视觉 障碍 的 用 户 来 说 ， 其 他 类 
型 的 UI 交 互 提示 是 有 必要 的 。 


幸运 的 是 ， 我 们 可 以 很 轻松 的 给 一 个 Ul 元 素 加 上 标签 ， 这 样 类 似 于 TalkBack 这 样 的 基于 语音 
的 Accessibility Service 就 可 以 将 标签 的 内 容 朗 读 出 来 。 如 果 你 的 标签 在 整个 应 用 的 生命 周期 
中 不 太 可 能 会 发 生变 化 (比如 停止 或 者 购买 )， 你 就 可 以 在 XML 布局 文件 中 对 
android:contentDescription 属 性 进行 设置 。 代 码 如 下 : 


<Button 
android:id=”@+id/pause_button” 
android:src=”@drawable/pause” 
android:contentDescription=”@string/pause”/> 


然而 ， 在 很 多 情况 下 描述 的 内 容 是 基于 上 下 文 环境 的 ， 比 如 说 一 个 开关 按钮 的 状态 ， 或 者 在 
list 中 一 片 可 选 的 数据 项 。 在 运行 时 编辑 内 容 描述 可 以 使 用 setContentDescription() 方 法 ， 代 码 
如 下 : 


String contentDescription = "Select " + strValues[position]; 
label.setContentDescription(contentDescription); 


将 以 上 功能 添加 进 您 的 代码 是 提高 您 应 用 可 达 性 的 最 简单 的 方法 。 尝 试 着 将 那些 有 用 的 地 方 
都 加 入 内 容 描述 ， 但 同时 要 避免 像 web 开 发 者 那样 将 所 有 的 元 素 都 标注 ， 那 样 会 产生 大 量 的 无 
用 信息 。 比 如 说 ， 不 要 将 应 用 图 标的 内 容 描 述 设置 为 应 用 图 标 ，。 这 只 会 对 用 户 的 浏览 产生 干 
ihe 


来 试 试 吧 | 下 载 TalkBack( 谷 歌 开 发 的 一 款 可 达 性 应 用 )， 在 Settings > Accessibility > 
TalkBack 将 它 开启 。 然 后 使 用 你 的 应 用 听 听 看 TalkBack 发 出 的 语音 提示 。 


设计 焦点 导航 


你 的 应 用 除了 支持 触摸 操作 外 ， 更 应 该 支持 其 他 的 导航 方式 。 很 多 Android 设 备 不 仅仅 提供 了 
触摸 屏 ， 还 提供 了 其 他 的 导航 硬件 比如 说 十 字 键 、 方 向 键 、 轨 迹 球 等 等 。 除 此 之 外 ， 最 新 的 
Android 发 行 版 本 也 支持 蓝牙 或 USB 的 外 接 设 备 ， 比 如 键盘 等 等 。 


为 了 实现 这 种 方式 的 导航 ， 一 切 用 户 可 以 用 来 可 导航 的 元 素 (navigational elements) 都 需要 设 
置 为 focusable (AA) , 它 可 以 在 运行 时 通过 View.setFocusable() 方 法 来 进行 设 定 ， 或 者 也 可 
以 在 XML 布 局 文件 中 使 用 android:focusable 来 设置 。 


每 个 UI 控件 有 四 个 属 

性 ，android:nextFocusUp,android:nextFocusDown,android:nextFocusLeft,android:nextFocu 
SRight, 用 户 在 导航 时 可 以 利用 这 些 属 性 来 指定 下 一 个 焦点 的 位 置 。 系 统 会 自动 根据 布局 的 方 
向 来 确定 导航 的 顺序 ， 如 果 在 您 的 应 用 中 系统 提供 的 方案 并 不 合适 ， 您 可 以 用 这 些 属 性 来 进 
行 自 定义 的 修改 。 


比如 说 ， 下 面 就 是 一 个 关于 按钮 和 标签 的 例子 ， 他 们 都 是 可 聚焦 的 (focusable)， 按 向 下 键 会 
将 焦点 从 按钮 移 到 文字 上 ， 按 向 上 会 重新 将 依 点 移 到 按钮 上 。 


«Button android:id="@+id/doSomething" 
android:focusable="true" 
android:nextFocusDown=”@id/label” 

> 

«TextView android:id="@+id/label" 
android: focusable="true” 
android: text="@string/labelText" 
android:nextFocusUp=”"@id/doSomething” 

= 


证 实 您 的 应 用 运行 正确 的 直观 方法 ， 最 简单 的 方式 就 是 在 Android 庶 拟 机 里 运行 您 的 应 用 ， 然 
后 使 用 应 拟 器 的 方向 键 来 在 各 个 元 素 之 间 导 航 ， 使 用 OK 按钮 来 代替 触摸 操作 。 


触发 可 达 性 事件 


如 果 你 在 你 的 Android 框 架 中 使 用 了 View 组 件 ， 当 你 选中 了 一 个 View 或 者 是 焦点 变化 的 时 候 ， 
可 达 性 事件 (AccessibjiityEvenb 都 会 产生 。 这 些 事件 会 被 传递 到 Accessibility Service 中 进行 处 
理 ， 实现 一 些 辅助 功能 ， 如 语音 提示 等 。 


如 果 你 写 了 一 个 自 定义 的 View， 请 确保 它 在 合适 的 时 候 产 生 事 件 。 使 
用 senqdAccessibilityEvent(int) 况 数 可 以 产生 可 达 性 事件 ， 其 中 的 参数 表示 事件 的 类 型 。 完 整 的 
可 达 性 事件 类 型 可 查阅 AccessibilityEvent 参 考 文档 。 


比如 说 ， 你 拓展 了 一 个 图 片 的 View， 你 希望 在 它 聚 焦 的 时 候 使 用 键盘 打字 可 以 在 其 中 插入 题 
注 ， 这 时 候 发 送 一 个 TYPE_ VIEW _TEXT_CHANGED 事 件 就 非常 合适 ， 尽 管 它 不 是 本 身 就 构 
建 在 这 个 图 片 View 中 的 。 产 生 事件 的 代码 如 下 : 


public void onTextChanged(String before, String after) { 


if (AccessibilityManager.getInstance(mContext).isEnabled()) 1 
sendAccessibilityEvent(AccessibilityEvent.TYPE VIEW TEXT CHANGED); 


} 
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请 确保 您 在 添加 可 达 性 功能 后 测试 它 的 有 效 性 。 为 了 测试 内 容 描 述 可 达 性 事件 ， 请 安装 并 局 
用 一 个 Accessibility Service。 比 如 说 使 用 TalkBack， 它 是 一 个 免费 的 开源 的 屏幕 读 取 软 件 ， 
可 在 Google Play 上 进行 下 载 。Service 启 动 后 ， 请 测试 您 应 用 中 所 有 的 功能 ， 同 时 听 听 
TalkBack 的 语音 反馈 。 


同时 ， 尝 试 着 用 一 个 方向 控制 器 来 控制 你 的 应 用 ， 而 非 使 用 直接 触摸 的 方式 。 你 可 以 使 用 一 
个 物理 设备 ， 比 如 十 字 键 、 轨 迹 球 等 。 如 果 没 有 条 件 ， 可 以 使 用 android 上 庶 拟 器 ， 它 提供 了 虚 
拟 的 按键 控制 。 

在 测试 导航 与 反馈 的 同时 ， 和 在 没有 任何 视觉 提示 的 情况 下 ， 应 该 对 你 的 应 用 大 概 是 一 个 什 
么 样子 有 所 认识 。 出 现 问题 就 修复 优化 它们 ， 最 终 就 会 开发 出 一 个 更 易 用 可 达 的 Android 程 
序 。 


开发 辅助 服务 


编写 :KOST - Æ x-:http://developer.android.com/training/accessibility/service.html 
本 课程 将 教 您 : 
1. 创建 可 达 性 服务 (Accessibility Service) 
2. 配置 可 达 性 服务 (Accessibility Service) 
3. 响应 可 达 性 事件 (AccessibilityEvents) 
4. 从 View 层 级 中 提取 更 多 信息 


Accessibility Service 是 Android 系 统 框架 提供 给 安装 在 设备 上 应 用 的 一 个 可 选 的 导航 反馈 特 
性 。Accessibility Service 可 以 替代 应 用 与 用 户 交流 反馈 ， 比 如 将 文本 转化 为 语音 提示 ， 或 是 
用 户 的 手指 悬 停 在 屏幕 上 一 个 较 重 要 的 区 域 时 的 触摸 反馈 等 。 本 课程 将 教 您 如 何 创建 一 个 
Accessibility Service， 同 时 处 理 来 自 应 用 的 信息 ， 并 将 这 些 信息 反馈 给 用 户 。 


创建 Accessibility Service 


Accessibility Service 可 以 绑 定 在 一 个 正常 的 应 用 中 ， 或 者 是 单独 的 一 个 Android 项 目 都 可 以 。 
创建 一 个 Accessibility Service 的 步骤 与 创建 普通 Service 的 步骤 相似 ， 在 你 的 项 目 中 创建 一 个 
继承 于 AccessibilityService 的 类 : 


package com.example.android.apis.accessibility; 

import android.accessibilityservice.AccessibilityService; 

public class MyAccessibilityService extends AccessibilityService ( 
@Override 


public void onAccessibilityEvent(AccessibilityEvent event) { 


} 


QOverride 
public void onInterrupt() { 


} 


与 其 他 Service 类 似 ， 你 必须 在 manifest 文 件 当 中 声明 这 个 Service。 记 得 标明 它 监 听 处 理 
了 android.accessibilityservice 事件 ， 以 便 Service 在 其 他 应 用 产生 AccessibilityEvent 的 时 候 
被 调用 。 


«application ...> 


«service android:name=".MyAccessibilityService"> 
<intent-filter> 
<action android:name="android.accessibilityservice.AccessibilityService" /> 
</intent-filter> 


</service> 


</application> 


如 果 你 为 这 个 Service 创 建 了 一 个 新 项 目 ， 且 仅仅 是 一 个 Service 而 不 准备 做 成 一 个 应 用 ， 那 么 
你 就 可 以 移 除 启动 的 Activity( 一 般 为 MainActivity.java)， 同 样 也 记得 在 manifest 中 将 这 个 
Activity 声 明 移 除 。 


配置 Accessibility Service 

设置 Accessibility Service 的 配置 变量 会 告诉 系统 如 何 让 Service 运 行 与 何 时 运行 。 你 希望 响应 
哪 种 类 型 的 事件 ? Service 是 否 对 所 有 的 应 用 有 效 还 是 对 部 分 指定 包 名 的 应 用 有 效 ? 使 用 哪些 
不 同类 型 的 反馈 人? 


你 有 两 种 设置 这 些 变量 属性 的 方法 ， 一 种 向 下 兼容 的 办 法 是 通过 代码 来 进行 设 定 ， 使 
用 setserviceInfo (android.accessibilityservice.AccessibilityServicelnfo)。 你 需要 重 写 
(override) onserviceconnected() 方法 ， 并 在 这 里 进行 Service 的 配置 。 





@Override 
public void onServiceConnected() { 
// Set the type of events that this service wants to listen to. Others 
// won't be passed to this service. 
info.eventTypes - AccessibilityEvent.TYPE VIEW CLICKED | 
AccessibilityEvent.TYPE VIEW FOCUSED; 


// If you only want this service to work with specific applications, set their 
// package names here. Otherwise, when the service is activated, it will listen 
// to events from all applications. 
info.packageNames - new String[] 

{"com.example.android.myFirstApp", "com.example.android.mySecondApp"); 


// Set the type of feedback your service will provide. 
info.feedbackType - AccessibilityServiceInfo.FEEDBACK SPOKEN; 


// Default services are invoked only if no package-specific ones are present 
// for the type of AccessibilityEvent generated. This service *is* 

// application-specific, so the flag isn't necessary. If this was a 

// general-purpose service, it would be worth considering setting the 

// DEFAULT flag. 


// info.flags - AccessibilityServiceInfo.DEFAULT; 
info.notificationTimeout - 100; 


this.setServiceInfo(info); 


4 Android 4.0 之 后 ， 就 用 另 一 种 方式 来 设置 了 : 通过 设置 XML 文件 来 进行 配置 。 一 些 特性 的 
选项 比如 canRetrievewindowContent 仅仅 可 以 在 XML 可 以 配置 。 对 于 上 面 所 示 的 相应 的 配置 ， 
利用 XML 配置 如 下 : 


«accessibility-service 
android:accessibilityEventTypes-"typeViewClicked|typeViewFocused" 
android: packageNames="com.example.android.myFirstApp, com.example.android.mySecon 


dApp" 
android: accessibilityFeedbackType="feedbackSpoken" 
android: notificationTimeout="100" 
android: settingsActivity="com.example.android.apis.accessibility.TestBackActivity" 
android: canRetrieveWindowContent="true" 
ie 


hh 


如 果 你 确定 是 通过 XML 进 行 配 置 ， 那 么 请 确保 在 manifest 文 件 中 通过 < meta-data > 标签 指定 
这 个 配置 文件 。 假 设 此 配置 文件 存放 的 地 址 为 : res/xml/serviceconfig.xml ， 那 么 标签 应 该 
如 下 : 


«service android:name=".MyAccessibilityService"> 
<intent-filter> 
<action android:name="android.accessibilityservice.AccessibilityService" /> 
</intent-filter> 
<meta-data android:name="android.accessibilityservice" 
android: resource="@xml/serviceconfig" /> 


</service> 


"44 22 Accessibility Event 


现在 你 的 Service 已 经 配置 好 并 可 以 监听 Accessibility Event 了 ， 来 写 一些 响 应 这 些 事件 的 代码 
吧 | 首先 就 是 要 重 写 onAccessibilityEvent(AccessibilityEvent) 方 法 ， 在 这 个 方法 中 ， 使 

用 getEventType() 来 确定 事件 的 类 型 ， 使 用 getContentDescription() 来 提取 产 生 事 件 的 View 
的 相关 的 文本 标签 。 


@Override 
public void onAccessibilityEvent(AccessibilityEvent event) { 
final int eventType = event.getEventType(); 
String eventText = null; 
switch(eventType) { 
case AccessibilityEvent.TYPE VIEW CLICKED: 


eventText = "Focused: "; 
break; 
case AccessibilityEvent.TYPE VIEW FOCUSED: 
eventText - "Focused: "; 
break; 


eventText = eventText + event.getContentDescription(); 
// Do something nifty with this text, like speak the composed string 


// back to the user. 
speakToUser (eventText) ; 


从 View 层 级 中 提取 更 多 信息 


这 一 步 并 不 是 必要 步骤 ， 但 是 却 非常 有 用 。Android 4.0 版 本 中 增加 了 一 个 新 特性 ， 就 是 能 够 
用 AccessibilityService 来 遍历 View 层 级 ， 并 从 产生 Accessibility 事件 的 组 件 与 它 的 父子 组 件 中 
提取 必要 的 信息 。 为 了 实现 这 个 目的 ， 你 需要 在 XML 文件 中 进行 如 下 的 配置 


android:canRetrieveWindowContent-"true" 


一 旦 完成 ， 使 用 getSource()) 获 取 一 个 AccessibilityNodelnfo 对 象 ， 如 果 触 发 事件 的 窗口 是 活 
动 窗口 ， 该 调用 只 返回 一 个 对 象 ， 如 果 不 是 , 它 将 返回 null， 做 出 相应 的 反响 。 下 面 的 示例 是 一 
个 代码 片段 , 当 它 接收 到 一 个 事件 时 ,执行 以 下 步骤 : 


^om 


立即 获取 到 产生 这 个 事件 的 Parent 

在 这 个 Parent 中 了 寻找 文本 标签 或 勾 选 杠 

如 果 找 到 ， 创 建 一 个 文本 内 容 来 反馈 给 用 户 ， 提 示 内 容 和 是 否 已 名 选 。 
如 果 当 遍历 View 的 时 候 某 处 返回 了 null 值 ， 那 么 就 直接 结束 这 个 方法 。 


// Alternative onAccessibilityEvent, that uses AccessibilityNodeInfo 


@Override 
public void onAccessibilityEvent(AccessibilityEvent event) { 


AccessibilityNodeInfo source = event.getSource(); 
if (source == null) { 
re tun; 


// Grab the parent of the view that fired the event. 
AccessibilityNodeInfo rowNode = getListItemNodeInfo(source); 
if (rowNode == null) { 

fetum 


// Using this parent, get references to both child nodes, the label and the checkb 
OX. 
AccessibilityNodeInfo labelNode = rowNode.getChild(9); 
if (labelNode == null) { 
rowNode.recycle(); 
re EU 


AccessibilityNodeInfo completeNode = rowNode.getChild(1); 
if (completeNode == null) { 

rowNode.recycle(); 

return; 


// Determine what the task is and whether or not it's complete, based on 
// the text inside the label, and the state of the check-box. 
if (rowNode.getChildCount() < 2 || !rowNode.getChild(i).isCheckable()) { 
rowNode.recycle(); 
return; 


CharSequence taskLabel - labelNode.getText(); 
final boolean isComplete - completeNode.isChecked(); 
String completeStr - null; 


if (isComplete) { 
completeStr - getString(R.string.checked); 
} else f 
completeStr = getString(R.string.not checked); 


} 
String reportStr = taskLabel + completeStr; 


speakToUser(reportStr); 


现在 你 已 经 实现 了 一 个 完整 可 运行 的 Accessibility Service。 尝 试 着 调整 它 与 用 户 的 交互 方式 
吧 | 比如 添加 语音 引擎 ， 或 者 添加 震动 来 提供 触觉 上 的 反馈 都 是 不 错 的 选择 | 


管理 系统 UI 


^h 5 :KOST - 原文 :http://developer.android.com/training/system-ui/index.html 


System Bar 是 用 来 展示 通知 、 表 现 设备 状态 和 完成 设备 导航 的 屏幕 区 域 。 通 常 上 来 说 ， 系 统 
ye 
而 照片 、 视 频 等 这 类 沉浸 式 的 应 用 可 以 临时 弱化 系统 栏 图 标 来 创造 一 个 更 加 专注 的 体验 环 
境 ， 甚 至 可 以 完全 隐藏 系统 Bar 。 





Figure 1. System bars， 包 含 [1] 状 态 栏 ， 和 [2] 寻 航 栏 。 


如 果 你 对 Android Design Guide 很 熟悉 ， 你 应 该 已 经 知道 遵照 标准 的 Android UI Guideline 与 
遵循 模式 来 设计 App 的 重要 性 。 在 你 修改 系统 栏 之 前 ， 你 应 该 仔细 的 考虑 一 下 用 户 的 需求 与 预 
期 ， 因 为 它们 是 操作 设备 和 观察 设备 状态 的 的 常规 途径 。 


这 节 课 描述 了 如 何在 不 同 版 本 的 Android 上 隐藏 或 淡化 系统 栏 ， 来 营造 一 个 沉浸 式 的 用 户 体 
验 ， 同 时 做 到 快速 的 访问 与 操作 系统 栏 。 


Sample 


ImmersiveMode - http://developer.android.com/samples/ImmersiveMode/index.html 


Lessons 


e 淡化 系统 栏 


学 习 如 何 淡化 和 隐藏 状态 栏 与 导航 栏 


o 


e 隐藏 状态 栏 

学 习 如 何在 不 同 版 本 的 Android 上 隐藏 状态 栏 。 
e 隐藏 导航 栏 

学 习 如 何 隐藏 导航 栏 。 
e 全 屏 沉 浸 式 应 用 


学 习 如 何在 你 的 App 中 创建 沉浸 模式 。 


响应 UI 可 见 性 的 变化 


学 习 如 何 注册 一 个 监听 器 来 监听 系统 UI 可 见 性 的 变化 ， 以 便于 相应 的 调整 App 的 Ul。 


淡化 系统 Bar 


编写 :KOST - Æ x-:http;//developer.android.com/training/system-ui/dim.html 


本 课程 将 向 你 讲解 如 何在 Android 4.0(API level 14) 与 更 高 的 的 系统 版 本 上 淡化 系统 栏 (System 
bar, 状 态 栏 与 导航 栏 )。 早 期 版 本 的 Android 没 有 提供 一 个 自 带 的 方法 来 淡化 系统 栏 。 

当 你 使 用 这 个 方法 的 时 候 ， 内 容 区 域 并 不 会 发 生 大 小 的 变化 ， 只 是 系统 栏 的 图 标 会 收 起 来 。 

一 旦 用 户 触 摸 状态 栏 或 者 是 导航 栏 的 时 候 ， 这 两 个 系统 栏 就 又 都 会 完全 显示 (无 透明 度 ) © 

这 种 方法 的 优势 是 系统 栏 仍然 可 见 ， 但 是 它们 的 细节 被 隐藏 掉 了 ， 因 此 可 以 在 不 牺牲 快捷 访 

问 系统 栏 的 情况 下 创建 一 个 沉浸 式 的 体验 。 


这 节 课 将 教 您 


1， 淡 化 状态 栏 和 导航 栏 
2， 显 示 状 态 栏 和 导航 栏 


同时 您 应 该 阅读 


e Action Bar API 指南 
e Android Design Guide 


淡化 状态 栏 和 系统 栏 


如 果 要 淡化 状态 和 通知 栏 ， 在 版 本 为 4.0 以 上 的 Android 系 统 上 ， 你 可 以 像 如 下 使 


用 svsTEM UI FLAG LOW PROFILE 这 个 标签 。 


// This example uses decor view, but you can use any visible view. 
View decorView - getActivity().getWindow().getDecorView(); 
int uiOptions - View.SYSTEM UI FLAG LOW PROFILE; 


一 旦 用 户 触 摸 到 了 状态 栏 或 者 是 系统 栏 ， 这 个 标签 就 会 被 清除 ， 使 系统 栏 重 新 显现 〈 无 透明 
E) 。 在 标签 被 清除 的 情况 下 ， 如 果 你 想 重 新 淡化 系统 栏 就 必须 重新 设 定 这 个 标签 。 

图 1 展示 了 一 个 图 库 中 的 图 片 ， 界 面 的 系统 栏 都 已 被 淡化 (需要 注意 的 是 图 库 应 用 完全 隐藏 状 
态 栏 ， 而 不 是 淡化 它 ) ; 注意 导航 栏 (图 片 的 右 侧 ) 上 变 暗 的 白色 的 小 点 ， 他 们 代表 了 被 隐 
藏 的 导航 操作 。 


图 1. 淡 化 的 系统 栏 


图 2 展示 的 是 同一 张 图 片 ， 系 统 栏 处 于 显示 的 状态 。 


图 2. 显 示 的 系统 栏 





如 果 你 想 动态 的 清除 显示 标签 ， 你 可 以 使 用 setsystemuivisibility() 方法 : 


View decorView = getActivity().getWindow().getDecorView(); 
// Calling setSystemUiVisibility() with a value of © clears 
"/alslagss 

decorView. setSystemUiVisibility(0); 


隐藏 状态 栏 


编写 :KOST - 原文 :http://developer.android.com/training/system-ui/status.html 
这 节 课 将 教 您 


1. 在 4.0 及 以 下 版 本 中 隐藏 状态 栏 
2. 在 4.1 及 以 上 版 本 中 隐藏 状态 栏 
3. 在 4.4 及 以 上 版 本 中 隐藏 状态 栏 
4. 让 内 容 显示 在 状态 栏 之 后 

5. 同步 状态 栏 与 Action Bar 的 变化 


同时 您 应 该 阅读 


e Action Bar API 指南 
e Android Design Guide 


本 课程 将 教 您 如 何在 不 同 版 本 的 Android 下 隐藏 状态 栏 。 隐 藏 状态 栏 (或 者 是 导航 栏 ) 可 以 让 
内 容 得 到 更 多 的 展示 空间 ， 从 而 提供 一 个 更 加 沉浸 式 的 用 户 体验 。 


图 1 展示 了 显示 状态 栏 的 界面 


oe 


è System UI 





图 1. 显示 状态 栏 . 


图 2 展示 了 隐藏 状态 栏 的 界面 。 请 注意 ，Action Bar 这 个 时 候 也 被 隐藏 了 。 请 永远 不 要 在 隐藏 
状态 栏 的 时 候 显 示 Action Bar ° 
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图 2. 隐藏 状态 栏 . 


在 4.0 及 以 下 版 本 中 隐藏 状态 栏 


在 Android 4.0 及 更 低 的 版 本 中 ， 你 可 以 通过 设置 windowManager 来 隐藏 状态 栏 。 你 可 以 动态 的 
隐藏 ， 也 可 以 在 你 的 manifest 文 件 中 设置 Activity 的 主题 。 如 果 你 的 应 用 的 状态 栏 在 运行 过 程 
中 会 一 直 隐 藏 ， 那 么 推荐 你 使 用 改写 manifest 设 定 主题 的 方法 (严格 上 来 讲 ， 即 便 设 置 了 
manifest 你 也 可 以 动态 的 改变 界面 主题 ) o 

<application 


android: theme="@android:style/Theme.Holo.NoActionBar.Fullscreen" > 


</application> 


设置 主题 的 优势 是 : 


e 易于 维护 ， 且 不 像 动态 设置 标签 那样 容易 出 错 
© 有 更 流畅 的 Ul 转换， 因为 在 初始 化 你 的 Activity 之 前 ， 系 统 已 经 得 到 了 需要 泻 染 UI| 的 信息 


另 一 方面 我 们 可 以 选择 使 用 windowManager 来 动态 隐藏 状态 栏 。 这 个 方法 可 以 更 简单 的 在 用 户 
与 App 进 行 交 互 式 展 示 与 隐藏 状态 栏 。 
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public class MainActivity extends Activity { 


@Override 
protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
// If the Android version is lower than Jellybean, use this call to hide 
// the status bar. 
if (Build.VERSION.SDK_INT < i6) { 
getWindow().setFlags(WindowManager .LayoutParams.FLAG FULLSCREEN, 
WindowManager.LayoutParams.FLAG FULLSCREEN); 


} 
setContentView(R.layout.activity main); 
} 
} 
当 你 设置 hell 标签 之 后 〈 无 论 是 通过 Activity 主 题 还 是 动态 设置 ) ， 这 个 标签 都 会 一 


直 生 效 直 到 你 清除 它 。 


设置 了 FLAG_LAYOUT_IN_SCREEN 之 后 ， 你 可 以 拥有 与 启用 FLAG_FULLSCREEN 后 相同 的 屏幕 区 


域 。 这 个 方法 防止 了 状态 栏 隐藏 和 展示 的 时 候 内 容 区 域 的 大 小 变化 。 


在 4.1 及 以 上 版 本 中 隐藏 状态 栏 


在 Android 4.1(API level 16) 以 及 更 高 的 版 本 中 ， 你 可 以 使 用 setSystemUiVisibility()) 来 进行 动 
态 隐藏 。 setsystemuivisibility() 在 View 层 面 设置 了 UI 的 标签 ， 然 后 这 些 设置 被 整合 到 了 


Window 层 面 。 — A 给 了 你 一 个 比 设 置 WindowManager 标签 更 加 粒度 
操作 。 下 面 这 段 代码 隐藏 了 状态 


View decorView = getWindow().getDecorView(); 

// Hide the status bar. 

int uiOptions - View.SYSTEM UI FLAG FULLSCREEN; 
decorView.setSystemUiVisibility(uiOptions); 

// Remember that you should never show the action bar if the 
// status bar is hidden, so hide that too if necessary. 
ActionBar actionBar - getActionBar(); 

actionBar.hide(); 


注意 以 下 几 点 : 


度 化 的 


e. 一 旦 UI 标签 被 清除 (比如 跳 转 到 另 一 个 Activity), 如 果 你 还 想 隐藏 状态 栏 你 就 必须 再 次 设 定 


它 。 详 细 可 以 看 第 五 节 如 何 监 听 并 响应 UI 可 见 性 的 变化 。 


e 在 不 同 的 地 方 设置 UI 标签 是 有 所 区 别 的 。 如 果 你 在 Activity 的 onCreate() 方 法 中 隐藏 系统 


栏 ， 当 用 户 按 下 home 键 系统 栏 就 会 重新 显示 。 当 用 户 再 重新 打开 Activity 的 时 候 ， 


onCreate() 不 会 被 调用 ， 所 以 系统 栏 还 会 保持 可 见 。 如 果 你 想 让 在 不 同 Activity 之 间 切 换 


时 ， 系 统 UI 保 持 不 变 ， 你 需要 在 onResume() 与 onWindowFocusChaned() 里 设 定 Ul 标 
e setSystemUiVisibility() 仅 仅 在 被 调用 的 View 显 示 的 时 候 才 会 生效 。 
e. 当 从 View 导 航 到 别 的 地 方 时 ， 用 setSystemUiVisibility() 设 置 的 标签 会 被 清除 。 


让 内 容 显 示 在 状态 栏 之 后 


在 Android 4.1 及 以 上 版 本 ， 你 可 以 将 应 用 的 内 容 显示 在 状态 栏 之 后 ， 这 样 当 状态 栏 显示 与 隐 
藏 的 时 候 ， 内 容 区 域 的 大 小 就 不 会 发 生变 化 。 要 做 到 这 个 效果 ， 我 们 需要 用 
到 svsTEM UI FLAG LAYOUT FULLSCREEN 这 个 标志 。 同 时 ， 你 也 有 可 能 需 


要 SYSTEM_UI_FLAG_LAYOUT_STABLE 这 个 标志 来 帮助 你 的 应 用 维持 一 个 稳定 的 布局 。 








当 使 用 这 种 方法 的 时 候 ， 你 就 需要 来 确保 应 用 中 特定 区 域 不 会 被 系统 栏 掩盖 (比如 地 图 应 用 
中 一 些 自 带 的 操作 区 域 ) 。 如 果 被 覆盖 了 ， 应 用 可 能 就 会 无 法 使 用 。 在 大 多 数 的 情况 下 ， 你 
可 以 在 布局 文件 中 添加 android:fitsSystemwindows 标签 ， 设 置 它 为 true。 它 会 调整 父 
ViewGroup 使 它 留 出 特定 区 域 给 系统 栏 ， 对 于 大 多 数 应 用 这 种 方法 就 足够 了 。 


在 一 些 情况 下 ， 你 可 能 需要 修改 默认 的 padding 大 小 来 获取 合适 的 布局 。 为 了 控制 内 容 区 域 的 
布局 相对 系统 栏 ( 它 占据 了 一 个 叫做 “内 容 租 入 ”content insets 的 区 域 ) 的 位 置 ， 你 可 以 重 
写 fitSystemWindows(Rect insets) 方法 。 当 窗口 的 内 BARA RRR BIC 

Kt > fitSystemWindows() 方法 会 被 view 的 hierarchy 调 用 ， 让 View 做 出 相应 的 调整 适应 。 重 写 
这 个 方法 你 就 可 以 按 你 的 意愿 处 理 诅 入 区 域 与 应 用 的 布局 。 


同步 状态 栏 与 Action Bar 的 变化 


在 Android 4.1 及 以 上 的 版 本 ， 为 了 防止 在 Action Bar 隐 藏 和 显示 的 时 候 布局 发 生变 化 ， 你 可 以 
使 用 Action Bar 的 overlay 模 式 。 在 Overlay 模 式 中 ，Activity 的 布局 占据 了 所 有 可 能 的 空间 ， 好 
像 Action Bar 不 存在 一 样 ， 系 统 会 在 布局 的 上 方 绘制 Aciton Bar。 虽 然 这 会 遮盖 住 上 方 的 一 些 

布局 ， 但 是 当 Action Bar 显 示 或 者 隐藏 的 时 候 ， 系 统 就 不 需要 重新 改变 布局 区 域 的 大 小 ， 使 之 
无 缝 的 变化 。 


要 启用 Action Bar 的 overlay 模 式 ， 你 需要 创建 一 个 继承 自 Action Bar 主 题 的 自 定义 主题 ， 
将 android:windowActionBaroverlay 属性 设置 为 true。 要 了 解 详细 信息 ， 请 参考 添加 Action Bar 
课程 中 的 Action Bart) € & BE o 


设置 SYSTEM UI FLAG LAYOUT FULLSCREEN 来 让 你 的 activity 使 用 的 屏幕 区 域 与 设 

置 SYSTEM UI FLAG FULLSCREEN 时 的 区 域 相 同 。 当 你 需要 隐藏 系统 UI 时 ， 使 

用 SYSTEM_UI_FLAG_FULLSCREEN 。 这 个 操作 也 同时 隐藏 了 Action Bar ( 

为 windowActionBaroverlay="true" ) ， 当 同时 显示 与 隐藏 ActionBar 与 状态 栏 的 时 候 ， 使 用 一 
个 动画 来 让 他 们 相互 协调 。 





隐藏 系统 Bar 
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隐藏 导航 栏 


编写 :KOST - 原文 :http://developer.android.com/training/system-ui/navigation.html 

这 节 课 将 教 您 

1. 在 4.0 及 以 上 版 本 中 隐藏 导航 栏 

2. 让 内 容 显 示 在 导航 栏 之 后 
本 节 课 程 将 教 您 如 何 对 导航 栏 进行 隐藏 ， 这 个 特性 是 Android 4.0 () 版 本 中 引入 的 。 
即便 本 小 节 仅 关注 如 何 隐藏 导航 栏 ， 但 是 在 实际 的 开发 中 ， 你 最 好 让 状态 栏 与 导航 栏 同 时 消 
失 。 在 保证 导航 栏 多 于 再 次 访问 的 情况 下 ， 隐 藏 导 航 栏 与 状态 栏 使 内 容 区 域 占据 了 整个 显示 
空间 ， 因 此 可 以 提供 一 个 更 加 沉浸 式 的 用 户 体验 。 





图 1. 导航 栏 . 


在 4.0 及 以 上 版 本 中 隐藏 导航 栏 


你 可 以 在 Android 4.0 以 及 以 上 版 本 ， 使 用 SYSTEM_UI_FLAG_HIDE_NAVIGATION 标志 来 隐藏 导航 
兰 。 这 段 代 码 同时 隐藏 了 导航 栏 和 系统 栏 : 





View decorView = getWindow().getDecorView(); 





// Hide both the navigation bar and the « Jar 
/ / JI FLAG FUL N le on Iroid nd h e but a 





rule, you 
// hide the navigation bar. 

int uiOptions - View.SYSTEM UI FLAG HIDE NAVIGATION 
| View.SYSTEM UI FLAG FULLSCREEN; 





注意 以 下 几 点 


e 使 用 这 个 方法 时 ， 触 摸 屏 幕 的 任何 一 个 区 域 都 会 使 导航 栏 (与 状态 栏 ) 重新 显示 。 用 户 


的 交互 会 使 这 个 标签 SYSTEM UI FLAG HIDE NAVIGATION 被 清除 。 

e 一 旦 这 个 标签 被 清除 了 ， 如 果 你 想 再 次 隐藏 导航 栏 ， 你 就 需要 重新 对 这 个 标签 进行 设 
定 。 在 下 一 节 响 应 UI 可见 性 的 变化 中 ， 将 详细 讲解 应 用 监听 系统 UI 变化 来 做 出 相应 的 调 
整 操作 。 

e. 在 不 同 的 地 方 设置 UI 标签 是 有 所 区 别 的 。 如 果 你 在 Activity 的 onCreate() 方 法 中 隐藏 系统 
栏 ， 当 用 户 按 下 home 键 系统 栏 就 会 重新 显示 。 当 用 户 再 重新 打开 activity 的 时 候 ， 





onCreate() 不 会 被 调用 ， 所 以 系统 栏 还 会 保持 可 见 。 如 果 你 想 让 在 不 同 Activity 之 间 切 换 
i 系统 UI 保 持 不 变 ， 你 betta) eaten We d X X UM 


setSystemUiVisibility() 仅 仅 在 被 调用 的 View 显 示 的 时 候 才 会 生效 。 
当 从 View 导 航 到 别 的 地 方 时 ， 用 setSystemUiVisibility() 设 置 的 标签 会 被 清除 。 


2) 让 内 容 显 示 在 导航 栏 之 后 


在 Android 4.1 与 更 高 的 版 本 中 ， 你 可 以 让 应 用 的 内 容 显 示 在 导航 栏 的 后 面 ， 这 样 当 导航 栏 展 
示 或 隐藏 的 时 候 内 容 区 域 就 不 会 发 生 布 局 大 小 的 变化 。 可 以 使 

用 SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION 标签 来 做 到 这 个 效果 。 同 时 ， 你 也 有 可 能 需 

要 SYSTEM_UI_FLAG_LAYOUT_STABLE 这 个 标签 来 帮助 你 的 应 用 维持 一 个 稳定 的 布局 。 








当 你 使 用 这 种 方法 的 时 候 ， 就 需要 你 来 确保 应 用 中 特定 区 域 不 会 被 系统 栏 掩盖 。 更 详细 的 信 
息 可 以 浏览 隐藏 状态 栏 一 节 。 


全 屏 沉 浸 式 应 用 


全 屏 沉 浸 式 应 用 


编写 :KOST - 原文 :http://developer.android.com/training/system-ui/immersive.html 
这 节 课 将 教 您 


1， 选 择 一 种 沉浸 方式 
2. s 


Adnroid 4.4(API level 19) 中 引入 为 setsystemuivisibility() 引入 了 一 个 新 标 

签 SYSTEM UI FLAG IMMERSIVE ， 它 可 以 让 应 用 进入 站 正 的 全 屏 模式 。 当 这 个 标签 

与 SYSTEM UI FLAG HIDE NAVIGATION 和 SYSTEM UI FLAG FULLSCREEN 一 起 使 用 的 时 候 ， 导 航 栏 和 
状态 栏 就 会 隐藏 ， 让 你 的 应 用 可 以 接受 屏幕 上 任何 地 方 的 触摸 事件 。 





当 沉 浸 式 全 屏 模式 启用 的 时 候 ， 你 的 Activity 会 继续 接受 各 类 的 触摸 事件 。 用 户 可 以 通过 在 边 
缘 区 域 向 内 滑动 来 让 系统 栏 重新 显示 。 这 个 操作 清空 

了 svsTEM UI FLAG HIDE NAVIGATION (和 sYSTEM UI FLAG FULLSCREEN ， 如 果 有 的 话 ) 两 个 标签 ， 
因此 系统 栏 重 新 变 得 可 见 。 如 果 设 置 了 的 话 ， 这 个 操作 同时 也 触发 

了 view.onsystemuivisibilitychangeListener 。 然 而 ， 如 果 你 想 让 系统 栏 在 一 段 时 间 后 自动 隐 
藏 的 话 ， 你 应 该 使 用 svsrEM UI FLAG IMMERSIVE STICKY 标签 。 请 注意 ， 带 有 'sticky' 的 标签 不 会 
触发 任何 的 监听 器 ， 因 为 在 这 个 模式 下 展示 的 系统 栏 是 处 于 暂时 (transient) 的 状态 。 





图 1 展示 了 各 种 不 同 的 “沉浸 式 "状态 





图 1. 沉浸 模式 状态 . 
在 上 图 中 : 
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非 沉浸 模式 展示 了 应 用 进入 沉浸 模式 之 前 的 状态 。 也 展示 了 设置 IMMERSIVE 标签 后 
用 户 滑 动 展 示 系 统 栏 的 状态 。 用 户 滑动 

后 ， SYSTEM_UI_FLAG_HIDE_NAVIGATION 和 SYSTEM_UI_FLAG_FULLSCREEN 就 会 被 清 除 ， 系统 栏 
就 会 重新 显示 并 保持 可 见 。 请 注意 ， 最 好 的 实践 方式 就 是 让 所 有 的 UI 控件 的 变化 与 系统 
栏 的 显示 隐藏 保持 同步 ， 这 样 可 以 减少 屏幕 显示 所 处 的 状态 ， 同 时 提供 了 更 无 缝 平滑 的 
用 户 体验 。 因 此 所 有 的 UI 控件 跟随 系统 栏 一 同 显示 。 一 旦 应 用 进入 了 沉浸 模式 ， 相 应 的 
UI 控件 也 跟随 着 系统 栏 一 同 隐藏 。 为 了 确保 UI 的 可 见 性 与 系统 栏 保持 一 致 ， 我 们 需要 一 
个 监听 器 view. OnSystemUiVisibilityChangeListener 来 监听 系统 栏 的 变化 。 这 在 下 一 节 中 
将 详细 讲解 。 





2. 提示 气泡 第 一 次 进入 沉浸 模式 时 ， 系 统 将 会 显示 一 个 提示 气泡 ， 提 示 用 户 如 何 再 让 
系统 栏 显示 出 来 。 





Note : TI 了 测试 你 想 强制 显示 提示 气泡 ， 你 可 以 先 将 应 用 设 为 沉浸 模式 ， 然 后 
按 下 电源 键 进 入 锁 屏 模式 ， 并 在 5 秒 中 之 后 打开 屏幕 。 





3. 沉浸 模式 这 张 图 展示 了 隐藏 了 系统 栏 和 其 他 UI 控件 的 状态 。 你 可 以 设 


置 IMMERSIVE 和 IMMERSIVE_STICKY 来 进入 这 个 状态 。 


4. 粘性 标签 一 这 就 是 你 设置 了 IMMERSIVE_STICKY 标签 时 的 UI 状 态 ， 用 户 会 向 内 滑动 以 展 
示 系 统 栏 。 半 透明 的 系统 栏 会 临时 的 进行 显示 ， 一 段 时 间 后 自动 隐藏 。 滑动 的 操作 并 不 
会 清空 任何 标签 ， 也 不 会 触发 系统 UI 可 见 性 的 监听 器 ， 因 为 暂时 显示 的 导航 栏 并 不 被 认 
为 是 一 种 可 见 性 状态 的 变化 。 


Note: immersive 类 的 标签 只 有 在 

与 SYSTEM UI FLAG HIDE NAVIGATION , SYSTEM UI FLAG FULLSCREEN 中 一 个 或 两 个 一 起 使 用 的 
时 候 才 会 生效 。 你 可 以 只 使 用 其 中 的 一 个 ， 但 是 一 般 情 况 下 你 需要 同时 隐藏 状态 栏 和 导 
航 栏 以 达到 沉浸 的 效果 。 


选择 一 种 沉浸 方式 


SYSTEM UI FLAG IMMERSIVE 与 SYSTEM UI FLAG IMMERSIVE STICKY 都 提供 了 沉浸 式 的 体验 ， 但 是 


在 上 面 的 描述 中 ， 他 们 是 不 一 样 的 ， 下 面 讲 解 一 下 什么 时 候 该 用 哪 一 种 标签 。 


© 如 果 你 在 写 一 款 图 书 浏览 器 、 新 闻 杂 上 志 阅 读 器 ， 请 将 immersive 标签 
与 SYSTEM UI FLAG FULLSCREEN , SYSTEM UI FLAG HIDE NAVIGATION 一 起 使 用 。 因 为 用 户 可 能 
会 经 常 访问 Action Bar 和 一 些 UI 控件 ， 又 不 希望 在 翻 页 的 时 候 有 其 他 的 东西 进行 干 
扰 。 IMMERSIVE 在 该 种 情况 下 就 是 个 很 好 的 选择 。 

e 如 果 你 在 打造 一 款 真 正 的 沉浸 式 应 用 ， 而 且 你 希望 屏幕 边缘 的 区 域 也 可 以 与 用 户 进行 交 
互 ， 并 且 用 户 也 不 会 经 常 访 问 系统 Ul。 这 个 时 候 就 要 
将 IMMERSIVE STICKY 和 SYSTEM UI FLAG FULLSCREEN SYSTEM UI FLAG HIDE NAVIGATION 两 个 


标签 一 起 使 用 。 比 如 做 一 款 游 戏 或 者 绘图 应 用 就 很 合适 








e 如 果 你 在 打造 一 款 视频 播放 器 ， 并 且 需 要 少量 的 用 户 交互 操作 。 你 可 能 就 需要 之 前 版 本 
的 一 些 方法 了 (从 Android 4.0 开 始 ) 。 对 于 这 种 应 用 ， 简 单 的 使 


用 SYSTEM_UI_FLAG_FULLSCREEN 47 SYSTEM UI FLAG HIDE NAVIGATION 就 足够 了 ， 不 需要 使 





用 immersive 标签 。 


使 用 非 粘 性 沉浸 模式 


当 你 使 用 svsTEM UI FLAG IMMERSIVE 标签 的 时 候 ， 它 是 基于 其 他 设置 过 的 标签 
( SYSTEM UI FLAG HIDE NAVIGATION 和 SYSTEM UI FLAG FULLSCREEN ) 来 隐藏 系统 栏 的 。 当 用 户 向 


内 滑动 ， 系 统 栏 重 新 显示 并 保持 可 见 。 





用 其 他 的 UI 标签 (如 SYSTEM UI FLAG LAYOUT HIDE NAVIGATION 和 SYSTEM UI FLAG LAYOUT STABLE ) 
来 防止 系统 栏 隐藏 时 内 容 区 域 大 小 发 生变 化 是 一 种 很 不 错 的 方法 。 你 也 需要 确保 Action Barfe 
其 他 系统 UI 控件 同时 进行 隐藏 。 下 面 这 段 代码 展示 了 如 何在 不 改变 内 容 区 域 大 小 的 情况 下 ， 
隐藏 与 显示 状态 栏 和 导航 栏 。 








// This snippet hides the system bars. 
private void hideSystemUI() { 
// Set the IMMERSIVE flag. 
// Set the content to appear under the system bars so that the content 
// doesn't resize when the system bars hide and show. 
mDecorView.setSystemUiVisibility( 
View.SYSTEM UI FLAG LAYOUT STABLE 
| View.SYSTEM UI FLAG LAYOUT HIDE NAVIGATION 
| View.SYSTEM UI FLAG LAYOUT FULLSCREEN 
| View.SYSTEM UI FLAG HIDE NAVIGATION // hide nav bar 
| 
| 














View.SYSTEM UI FLAG FULLSCREEN // hide status bar 
View.SYSTEM UI FLAG IMMERSIVE); 


// This snippet shows the system bars. It does this by removing all the flags 
// except for the ones that make the content appear under the system bars. 
private void showSystemUI() { 
mDecorView.setSystemUiVisibility( 
View.SYSTEM UI FLAG LAYOUT STABLE 
| View.SYSTEM UI FLAG LAYOUT HIDE NAVIGATION 
| View.SYSTEM UI FLAG LAYOUT FULLSCREEN); 











你 可 能 同时 也 希望 在 如 下 的 几 种 情况 下 使 用 IMMERSIVE 标签 来 提供 更 好 的 用 户 体验 : 


e 注册 一 个 监听 器 来 监听 系统 UI 的 变化 。 

e 实现 onwindowFocuschanged() 函数 。 如 果 窗 口 获 取 了 焦点 ， 你 可 能 需要 对 系统 栏 进 行 隐 
藏 。 如 果 窗 口 失去 了 焦点 ， 比 如 说 弹出 了 一 个 对 话 框 或 菜单 ， 你 可 能 需要 取消 那些 将 要 
在 Handler .postDelayed() 或 其 他 地 方 的 隐藏 操作 ? 


e 实现 一 个 GestureDetector ^? 它 监听 了 onSingleTapUp(MotionEvent) 事件 可 以 使 用 户 点 
击 内 容 区 域 来 切换 系统 栏 的 显示 状态 。 单 纯 的 点 击 监 听 可 能 不 是 最 好 的 解决 方案 ， 因 为 
当 用 户 在 屏幕 上 拖 动 手指 的 时 候 (假设 点 击 的 内 容 占 据 了 整个 屏幕 ) ， 这 个 事件 也 会 被 
触发 。 


更 多 关于 此 话题 的 讨论 ， 可 以 观看 这 个 视频 DevBytes: Android 4.4 Immersive Mode 


使 用 粘性 沉浸 模式 


当 使 用 了 sYsTEM UI FLAG IMMERSIVE sTICKY 标签 的 时 候 ， 向 内 滑动 的 操作 会 让 系统 栏 临时 显 
示 ， 并 处 于 半 透 明 的 状态 。 此 时 没有 标签 会 被 清除 ， 系 统 UI 可 见 性 监听 器 也 不 会 被 触发 。 如 
果 用 户 没 有 进行 操作 ， 系 统 栏 会 在 一 段 时 间 内 自动 隐藏 。 


图 2 展示 了 当 使 用 IMMERSIVE_STICKY 标签 时 ， 半 透明 的 系统 栏 展 示 与 又 隐藏 的 状态 。 





图 2. 自动 隐藏 系统 栏 . 


下 面 是 一 段 实现 代码 。 一 旦 窗口 获取 了 焦点 ， 只 要 简单 的 设置 IMMERSIVE sTICkY 与 上 面 讨 论 
过 的 其 他 标签 即 可 。 
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@Override 
public void onWindowFocusChanged(boolean hasFocus) { 
super .onWindowFocusChanged(hasFocus) ; 
if (hasFocus) { 
decorView.setSystemUiVisibility( 
View.SYSTEM UI FLAG LAYOUT STABLE 
| View.SYSTEM UI FLAG LAYOUT HIDE NAVIGATION 
| View.SYSTEM UI FLAG LAYOUT FULLSCREEN 
| View.SYSTEM UI FLAG HIDE NAVIGATION 
| 
| 














View.SYSTEM UI FLAG FULLSCREEN 
View.SYSTEM UI FLAG IMMERSIVE STICKY); 





Notes : 如 果 你 想 实现 immersive sticky 的 自动 隐藏 效果 ， 同 时 也 需要 展示 你 自己 的 UI 
控件 。 你 只 需要 使 用 IMMERSIVE 与 Handler.postDelayed() 或 其 他 类 似 的 东西 ， 让 它 几 秒 
后 重新 进入 沉浸 模式 即 可 。 


响应 UI 可见 性 的 变化 


4% 5 :KOST - 原文 :http://developer.android.com/training/system-ui/visibility.html 


本 节 课 将 教 你 如 果 注 册 监 听 器 来 监听 系统 UI 可 见 性 的 变化 。 这 个 方法 在 将 系统 栏 与 你 自己 的 
UI 控件 进行 同步 操作 时 很 有 用 。 


EMT OT BS 


为 了 获取 系统 UI 可 见 性 变化 的 通知 ， 我 们 需要 对 View 注 
At view.onsystemuivisibilityChangeListener 监听 器 。 通 常 上 来 说 ， 这 个 View 是 用 来 控制 导航 
的 可 见 性 的 。 


例如 你 可 以 添加 如 下 代码 在 onCreate 中 


View decorView = getWindow().getDecorView(); 
decorView. setOnSystemUiVisibilityChangeListener 
(new View. OnSystemUiVisibilityChangeListener() { 
@Override 
public void onSystemUiVisibilityChange(int visibility) { 
// Note that system bars will only be "visible" if none of the 
// LOW PROFILE, HIDE NAVIGATION, or FULLSCREEN flags are set. 
if ((visibility & View.SYSTEM UI FLAG FULLSCREEN) == 0) { 
// TODO: The system bars are visible. Make any desired 
// adjustments to your UI, such as showing the action bar or 
// other navigational controls. 
} else { 
// TODO: The system bars are NOT visible. Make any desired 
// adjustments to your UI, such as hiding the action bar or 
// other navigational controls. 


3): 


保持 系统 栏 和 UI 同 步 是 一 种 很 好 的 实践 方式 ， 比 如 当 状 态 栏 显示 或 隐藏 的 时 候 进 行 ActionBar 


的 显示 和 隐藏 等 等 。 


创建 使 用 Material Design 的 应 用 


编写 : allenlsy - 原文 : https://developer.android.com/training/material/index.html 


Material Design 是 一 个 全 面 的 关于 视觉 ， 动 作 和 交互 的 指南 ， 实 现 跨 平 台 的 设计 。 要 在 你 的 
Android 应 用 中 使 用 Material Design ， 你 需要 遵从 Material Design 规格 文档 ， 来 使 用 
Android 5.0 中 新 添加 的 组 件 和 功能 。 


本 课 会 通过 以 下 方面 教 你 如 何 创建 Material Design 设计 的 应 用 : 


。 Material Design 主题 

e 用 于 卡片 和 列表 的 小 组 件 

。 定义 Shadows 与 Clipping 视 图 
e & € drawable 

e 自 定义 动画 


本 课 还 将 告诉 你 在 使 用 Material Design 时 如 何 兼容 Android 5.0 (API level 21) 之 前 的 版 本 。 


课程 
开始 使 用 Material Design 


学 习 如 何 升 级 应 用 ， 使 用 Material Design 特性 


使 用 Material Design 主题 

学 习 如 何 使 用 Material Design 主题 

用 于 卡片 和 列表 的 小 组 件 

学 习 如 何 创建 列表 和 卡片 视图 ， 使 得 应 用 和 其 他 系统 组 件 风格 统一 
定义 Shadows 与 Clipping 视 图 

学 习 如 何 设置 evaluation 来 自 定义 阴影 ， 以 及 创建 Clipping 视图 
使 用 Drawables 


学 习 如 何 创 建 矢量 Drawable 以 及 如 何 给 drawable 资源 着 色 


自 定 义 动画 
学 习 如 何 为 视图 和 Activity 切换 创建 自 定义 动画 
维护 兼容 性 


学 习 如 何 兼容 Android 5.0 以 下 的 版 本 


开始 使 用 Material Design 


编写 : allenlsy - 原文 : https://developer.android.com/training/material/get-started.html 
要 创建 一 个 Material Design 应 用 : 


1. 学 习 Material Design 规格 标准 

2. 应 用 Material Design 主题 

3. 创建 符合 Material Design 的 Layout 文件 
4. 定义 视图 的 elevation 值 来 修改 阴影 

5. 使 用 系统 组 件 来 创建 列表 和 卡片 

6 自 定义 动画 


维护 向 下 兼容 性 


你 可 以 添加 Material Design 特性 ， 同 时 保持 对 Android 5.0 之 前 版 本 的 兼容 。 更 多 信息 ， 请 
参见 维护 兼容 性 章节 。 


使 用 Material Design 更 新 现 有 应 用 


要 更 新 现 有 应 用 ， 使 其 使 用 Material Design， 你 需要 翻新 你 的 layout 文件 来 遵从 Material 
Design 标准 ， 并 确保 其 包含 了 正确 的 元 素 高 度 ， 触 摸 反 馈 和 动画 。 


使 用 Material Design 创建 新 的 应 用 

如 果 你 要 创建 使 用 Material Design 的 新 的 应 用 ，Material Design 指南 提供 了 一 套 跨 平台 统一 
的 设计 。 请 遵从 指南 ， 使 用 新 功能 来 进行 Android 应 用 的 设计 和 开发 。 

应 用 Material +% 


要 在 应 用 中 使 用 Material 主题 ， 需 要 定义 一 个 继承 于 android:Theme.Material 的 style X 
TF : 


<!-- res/values/styles.xml --> 
<resources> 
<!-- your theme inherits from the material theme --> 


«style name="AppTheme" parent="android:Theme.Material"> 
<!-- theme customizations --> 
</style> 
</resources> 


Material 主题 提供 了 更 新 后 的 系统 组 件 ， 使 你 可 以 设置 调 色 板 和 在 触摸 和 Activity 切换 时 使 用 
默认 的 动画 。 更 多 信息 ， 请 参见 Material 主题 章节 。 


设计 你 的 Layouts 


另外 ， 要 应 用 自 定义 的 Material 主题 ， 你 的 layout 应 该 要 符合 Material 设计 规范 。 在 设计 
Layout 时 ， 尤 其 要 注意 一 下 方面 : 


e 基准 线 网 格 

e Keyline 

e 间隙 

e 触摸 目标 的 大 小 
e Layout 结构 


定义 视图 的 Elevation 


视图 可 以 投射 阴影 ，elevation 值 决 定 了 阴影 的 大 小 和 绘制 顺序 。 要 设 定 elevation 值 ， 请 使 
用 android:elevation 属性 : 


«TextView 
android:id-"Q-id/my textview" 
android:layout width-"wrap content" 
android:layout height-"wrap content" 
android: text="@string/next" 
android: background="@color/white" 
android:elevation="5dp" /> 


新 的 translationz 属性 使 得 你 可 以 设计 临时 变更 elevation 494 ® » elevation 变化 在 做 触摸 
反馈 时 很 有 用 。 


更 多 信息 ， 请 参见 定义 阴影 和 Clipping 视图 章节 。 
创建 列表 和 卡片 
RecyclerView 是 一 个 植 入 性 更 强 的 ListView， 它 支持 不 同 的 layout 类 型 ， 并 可 以 提升 性 


能 。CardView 使 得 你 可 以 在 卡片 内 显示 一 部 分 内 容 ， 并 且 和 其 他 应 用 保持 外 观 一 致 。 以 下 是 
一 段 样 例 代码 展示 如 何在 layout 中 添加 CardView 


«android.support.v7.widget.CardView 
android:id-"Q-id/card view" 
android: layout_width="200dp" 
android: layout_height="200dp" 
card_view: cardCornerRadius="3dp"> 


</android.support.v7.widget .CardView> 


更 多 信息 ， 请 参见 列表 和 卡片 章节 。 


自 定义 动画 


Android 5.0 (API level 21) 包含 了 新 的 创建 自 定义 动画 APl。 比 如 ， 你 可 以 在 activity 中 定义 
进入 和 退出 activity 时 的 动画 。 


public class MyActivity extends Activity { 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
// enable transitions 
getWindow().requestFeature(Window.FEATURE CONTENT TRANSITIONS); 
setContentView(R.layout.activity my); 


public void onSomeButtonClicked(View view) { 
getWindow().setExitTransition(new Explode()); 
Intent intent - new Intent(this, MyOtherActivity.class); 
startActivity(intent, 
ActivityOptions 
.makeSceneTransitionAnimation(this).toBundle()); 


当 你 从 当前 activity 进入 另 一 个 activity 时 ， 退 出 切换 动画 会 被 调用 。 


想 学 习 更 多 新 的 动画 API， 参 见 自 定义 动画 章节 )。 


使 用 Material 的 主题 


编写 : allenlsy - 原文 : https://developer.android.com/training/material/theme.html 
新 的 Material 主题 提供 : 


e 系统 组 件 ， 用 于 设 定 调 色 板 
© 系统 组 件 的 触摸 反馈 动画 
e Activity 切换 动画 


你 可 以 根据 你 的 品牌 特征 修改 调 色 板 ， 从 而 自 定 义 Material 主题 。 你 可 以 通过 主题 属性 调整 
action bar 和 状态 栏 的 颜色 ， 就 像 下 图 一 样 : 


colorPrimary 


textColorPrimary 


colorPrimaryDark 


windowBackground 


navigationBarColor 





系统 组 件 拥有 新 的 设计 和 触摸 反馈 动画 。 你 可 以 自 定义 调 色 板 ， 反 馈 动画 和 Activity 切换 动 


RE 


Material 主题 被 定义 在 : 


e @android:style/Theme.Material (上 暗色 版 本 ) 
* @android:style/Theme.Material.Light (亮色 版 本 ) 


e  Qandroid:style/Theme.Material.Light.DarkActionBar 


Material Dark 


© Business 


Social 


CONTINUE CANCEL 











. 
Material Light - 
First Name: 
Last Name: 
Visit Type: Business 
©) Social 
CONTINUE CANCEL 


想 知 道 可 用 的 Material style 的 列表 ， 可 以 在 API 文档 中 参见 


Note: Material 主题 只 支持 Android 5.0 (API level 21) 及 以 上 版 本 。v7 Support 库 提 供 了 
一 些 组 件 的 Material Deisgn 样式 ， 也 支持 自 定义 调 色 板 。 更 多 信息 ， 请 参见 维护 兼容 性 


- 立 - 
z 


P o 


Ad 


自 定义 调 色 板 
在 根据 自己 的 品牌 自 定义 调 色 板 时 ， 你 需要 在 继承 material 主题 时 定义 theme 属性 。 


«resources» 
<!-- inherit from the material theme --> 
«style name-"AppTheme" parent="android:Theme.Material"> 


<!-- Main theme colors --> 
<!-- your app branding color for the app bar --> 
<item name="android:colorPrimary">@color/primary</item> 
<!-- darker variant for the status bar and contextual app bars --> 
<item name="android:colorPrimaryDark">@color/primary_dark</item> 
<!-- theme UI controls like checkboxes and text fields --> 
<item name="android:colorAccent">@color/accent</item> 
</style> 
</resources> 


自 定 义 状态 栏 


Material 主题 使 得 你 很 容易 自 定 义 状 态 栏 ， 你 可 以 设 定 适合 自己 品牌 的 颜色 ， 并 提供 足够 的 对 
比 度 ， 以 显示 白色 的 状态 图 标 。 设 置 状 态 栏 颜 色 时 ， 要 在 继承 Material 主题 时 设 定 
android:statsBarColor 属性 。 默 认 情 况 下 ， android:statusBarcolor 会 继承 


android:colorPrimaryDark 的 值 。 


你 也 可 以 在 状态 栏 的 背景 上 绘画 。 比 如 ， 你 想 让 位 于 照片 之 上 的 状态 栏 透 明 ， 并 保留 一 点 深 
色 渐 变 以 确保 白色 图 标 可 见 。 这 样 的 话 ， 设 定 android:statusBarColor 属性 为 
@android:color/transparent 并 调整 窗口 的 Flag 标记 。 你 也 可 以 用 
Window.setStatusBarColor() 来 实现 动画 或 淡 入 淡出 。 


Note: 状态 栏 必 须 随 时 保持 和 primary toolbar ( 即 顶 部 Actionbar， 译 者 注 ) 的 界线 清晰 。 
除了 一 种 情况 ， 即 在 状态 栏 后 面 显 示 图 片 或 媒体 内 容 时 之 外 ， 你 都 要 用 渐变 色 来 确保 前 
台 图 标 仍 然 可 见 。 


当 你 自 定 义 导 航 栏 和 状态 栏 时 ， 要 么 两 者 都 透明 ， 要 人 么 只 修改 状态 栏 。 其 他 情况 下 ， 导 航 栏 
应 该 保持 黑色 。 


主题 单独 视图 


XML layout 中 的 元 素 可 以 定义 android:theme 属性 ， 用 于 引用 主题 资源 。 这 个 属性 修改 了 自 
己 和 子 元 素 的 主题 ， 对 于 要 修改 局 部 颜色 主 题 的 情况 十 分 有 用 。 


创建 Lists 与 Cards 


编写 : allenlsy - 原文 : https://developer.android.com/training/material/lists-cards.html 


要 在 应 用 中 创建 复杂 的 列表 和 使 用 Material Design 的 卡片 列表 ， 你 可 以 使 用 RecyclerView 


和 CardView ? 


创建 列表 


RecyclerView 组 件 是 一 个 更 高 级 和 伸缩 性 更 强 的 ListView。 这 个 组 件 是 一 个 显示 大 量 数据 的 
容器 ， 通 过 维护 有 限量 的 View， 来 达到 滚动 时 的 高 效 。 当 你 的 数据 集 在 运行 过 程 中 会 根据 用 
户 行 为 或 网 络 事件 更 新 时 ， 应 该 使 用 RecyclerView ° 


RecyclerView 通过 以 下 方式 简化 显示 流程 ， 并 操作 大 量 数 据 : 


e 使 用 Layout manager 来 定位 元 素 
e 为 常用 操作 定义 默认 动画 ， 比 如 添加 或 移 除 元 素 


你 也 可 以 为 RecyclerView 自 定 义 Layout manager 和 动画 。 





Me o oe | 


图 1. The Recyclerview widget. 


要 使 用 RecyclerView 组 件 ， 你 需要 定义 一 个 adapter 和 layout manager。 创 建 adapter， 要 
继承 RecyclerView.Adapter 类 。 实 现 类 的 细节 取决 于 你 的 数据 集 和 视图 类 型 。 更 多 信 息 > A 
看 以 下 样 例 。 


Ali Connors 
Brunch this weekend? 


me, Scott, Jennifer 
Summer BBQ 


Sandra Adams 
Oui Oui 


Trevor Hansen 
Order Confirmation 


Britta Holt 
Recipe to try 


David Park 
Giants game 





Layout manager 把 元 素 视图 放 在 RecyclerView ^? 并 决定 什么 时 候 重用 不 可 见 的 元 素 视 图 。 
要 重用 (或 回收 ) 视图 时 ，layout manager 会 让 adapter 用 另外 的 元 素 内 容 替 换 视 图 内 的 内 
容 。 回 收 View 这 个 方法 能 提高 性 能 ， 因 为 它 避 免 了 创建 不 必要 的 view 对 象 ， 或 执行 昂贵 的 


findviewById() 查找 。 


Recyclerview 提供 以 下 内 建 的 layout manager: 


e LinearLayoutManager 用 于 显示 横向 或 纵向 的 滚动 列表 
e  GridLayoutManager 用 于 显示 方 格 元 素 
e StaggeredGridLayoutManager 在 staggered 方 格 中 显示 元 素 


创建 一 个 自 定 义 的 layout manager ， 要 继承 于 RecyclerView.LayoutManager X 


动画 


添加 和 删除 元 素 的 动画 在 RecyclerView 中 是 默认 被 启用 的 。 要 自 定义 动画 ， 你 需要 继 


ES RecyclerView.ItemAnimator 类 ， 使 用 RecyclerView.setItemAnimator() 方法 。 


LR 


以 下 代码 示例 了 如 何 添加 RecyclerView 到 一 个 Layout : 


«!-- A RecyclerView with some commonly used attributes --> 
«android.support.v7.widget.RecyclerView 
android: id="@+id/my_recycler_view" 
android:scrollbars="vertical" 
android: layout_width="match_parent" 
android: layout_height="match_parent"/> 


添加 RecyclerView 组 件 到 Layout 之 后 ， 获 得 一 个 到 RecyclerView 的 对 象 ， 连 接 它 到 Layout 
manager， 再 附 上 adapter 用 于 数据 显示 : 


public class MyActivity extends Activity { 
private RecyclerView mRecyclerView; 
private RecyclerView.Adapter mAdapter; 
private RecyclerView.LayoutManager mLayoutManager; 


@Override 

protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.my activity); 
mRecyclerView - (RecyclerView) findViewById(R.id.my recycler view); 


// use this setting to improve performance if you know that changes 
// in content do not change the layout size of the RecyclerView 
mRecyclerView.setHasFixedSize(true); 


// use a linear layout manager 
mLayoutManager - new LinearLayoutManager(this); 
mRecyclerView.setLayoutManager(mLayoutManager); 


// specify an adapter (see also next example) 
mAdapter - new MyAdapter(myDataset); 
mRecyclerView.setAdapter(mAdapter); 


Adapter 支持 获取 数据 集 元 素 ， 创 建 元 素 的 视图 ， 并 可 以 将 新 元 素 的 内 容 去 替代 不 可 见 元 素 视 
图 中 的 内 容 。 以 下 代码 展示 了 一 个 简单 的 实现 ， 其 中 的 数据 集 包含 了 一 个 字符 囊 数 组 ， 数 据 
元 素 用 TextView 显示 : 


创建 Lists 与 Cards 


public class MyAdapter extends RecyclerView.Adapter<MyAdapter.ViewHolder> { 
private String[] mDataset; 


// Provide a reference to the views for each data item 
// Complex data items may need more than one view per item, and 
// you provide access to all the views for a data item in a view holder 
public static class ViewHolder extends RecyclerView.ViewHolder ( 
// each data item is just a string in this case 
public TextView mTextView; 
public ViewHolder(TextView v) { 
super(v); 
mTextView - v; 


// Provide a suitable constructor (depends on the kind of dataset) 
public MyAdapter(String[] myDataset) { 
mDataset - myDataset; 


// Create new views (invoked by the layout manager) 
@Override 
public MyAdapter.ViewHolder onCreateViewHolder(ViewGroup parent, 
int viewType) { 
// create a new view 
View v = LayoutInflater.from(parent.getContext()) 
.inflate(R.layout.my text view, parent, false); 
// set the view's size, margins, paddings and layout parameters 


ViewHolder vh - new ViewHolder(v); 
return vh; 


// Replace the contents of a view (invoked by the layout manager) 

@Override 

public void onBindViewHolder(ViewHolder holder, int position) { 
// - get element from your dataset at this position 
// - replace the contents of the view with that element 
holder.mTextView.setText(mDataset[position]); 


// Return the size of your dataset (invoked by the layout manager) 
@Override 
public int getItemCount() { 

return mDataset.length; 
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F A & 12:30 


Top 10 Australian Beaches 


Number 10 
Whitehaven Beach = 
Whitsunday Island, Whitsunday Islands 


SHARE LEARN MORE 


Located two hours south of Sydney in the Southern 
Highlands of New South Wales, Kangaroo Valley... 


SHARE BOOK RESERVATION 





CardView 继承 于 FrameLayout 类 ， 它 可 以 在 卡片 中 显示 信息 ， 并 保持 在 不 同 平台 上 拥有 统 
一 的 风格 。CardView 组 件 可 以 设 定 阴影 和 圆 角 。 


要 创建 一 个 带 阴 影 的 卡片 2 使 用 card_view:cardElevation 属性 ° CardView 使 用 了 Android 
5.0 (API level 21) 中 的 丨 实 高 度 值 以 及 动态 阴影 效果 ， 在 5.0 以 下 的 版 本 中 有 编程 实现 阴影 的 
备 选 方案 。 更 多 内 容 ， 请 参见 保持 兼容 性 章节 。 


使 用 以 下 属性 来 自 定义 CardView : 


e 使 用 card view:cardCornerRadius 在 layout 中 设置 圆 角 
e 使 用 cardView.setRadius 在 代码 中 设置 圆 角 


e 使 用 card view:carBackgroundColor 来 设置 背景 颜色 


以 下 代码 展示 如 何在 layout 中 添加 CardView: 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
xmlns: tools="http://schemas.android.com/tools" 
xmlns:card_view="http://schemas.android.com/apk/res-auto" 

a 

<!-- A CardView that contains a TextView --> 
«android.support.v7.widget.CardView 

xmlns:card view-"http://schemas.android.com/apk/res-auto" 

android:id-z"Q-id/card view" 

android: layout_gravity="center" 

android: layout_width="200dp" 

android: layout_height="200dp" 

card view:cardCornerRadius-"4dp"» 


«TextView 
android: id="@+id/info_text" 
android: layout_width="match_parent" 
android: layout_height="match_parent" /> 
</android.support.v7.widget .CardView> 
</LinearLayout> 


更 多 信息 ， 参 见 CardView 的 API 文 档 。 


添加 依赖 


RecyclerView 和 CardView 都 是 v7 support 库 的 一 部 分 。 要 使 用 这 两 个 组 件 ， 在 你 的 Gradle 依 
赖 中 添加 两 个 模块 : 


dependencies { 


compile 'com.android.support:cardview-v7:21.0.-*' 
compile 'com.android.support:recyclerview-v7:21.0.-*' 


创建 Lists 与 Cards 
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3 Shadows 5 Clipping A 
编写 : allenlsy - 原文 : https://developer.android.com/training/material/shadows- 
clipping.html 


Material Design 引入 了 UI 元 素 深度 的 概念 。 深 度 可 以 帮助 用 户 理解 每 个 元 素 的 不 同 重要 性 ， 
让 用 户 集中 注意 力 做 手头 的 工作 。 


视图 的 elevation， 用 Z 属性 来 表示 ， 它 决定 了 阴影 的 大 小 : 更 大 的 乙 值 可 以 投射 出 更 大 更 柔 
软 的 阴影 。Z 值 较 大 的 视图 会 遮盖 住 Z 值 较 小 的 视图 。 不 过 ，Z 值 大 小 不 会 影响 视图 的 大 小 。 


阴影 是 由 被 投射 视图 的 上 级 视图 来 完成 绘制 ， 因 此 他 受 上 级 视图 影响 ， 附 着 在 上 级 视图 上 。 
Elevation 对 于 创建 临时 上 升 这 种 动画 同样 很 有 用 。 


更 多 信息 ， 请 参见 3D 空 间 中 的 对 象 。 


25-35. A n Elevation à. 


视图 的 乙 值 有 两 个 组 成 部 分 : 


e elevation: 静态 组 成 部 分 
e translation: 动态 部 分 ， 用 于 动画 


Z = elevation + translationZ 


图 1 - 不 同 深度 view 的 阴影 . 


在 layout 中 设置 视图 的 elevation， 要 使 用 android:elevation 属性 。 要 在 Activity 代 码 中 设置 
elevation， 使 用 view.setElevation() 方法 。 


要 设置 视图 的 translation， 使 用 view.setTranslationz() 方法 。 


新 的 ViewPropertyAnimator.z() 和 ViewPropertyAnimator.translationZ() 方法 使 你 可 以 很 容 
多 的 实现 elevation 动 画 。 更 多 信息 ， 请 查看 ViewPropertyAnimator 和 属性 动画 开发 指南 。 


你 也 可 以 使 用 StateListAnimator 来 声明 动画 。 这 非常 适用 于 要 通过 状态 改变 来 触发 动画 的 情 
况 ， 比 如 当 用 户 按 下 按钮 。 更 多 信息 ， 请 查看 Animate View State Changes ( 当 视 图 状态 变 
化 的 动画 ， 译 者 注 ) 。 


Z 值 的 计算 单位 是 dp。 


自 定 义 视 图 的 阴影 和 轮廓 


视图 背景 的 边界 决定 了 阴影 的 形状 。 轮 廓 是 一 个 图 形 对 象 的 外 围 形状 ， 决 定 了 触摸 反馈 动 
的 ripple 区 域 。 


假设 以 下 是 个 视图 : 


<TextView 
android:id="@+id/myview" 


android:elevation="2dp" 
android:background="@drawable/myrect" /> 


F X drawable X t 7] — ^ [f] f 69 4870 : 


«!-- res/drawable/myrect.xml --> 
<shape xmlns:android="http://schemas.android.com/apk/res/android" 
android: shape="rectangle"> 
<solid android:color="#42000000" /> 
«corners android: radius="5dp" /> 
</shape> 


这 个 视图 会 投影 出 圆 角 ， 因 为 背景 drawble 可 以 决定 视图 轮廓 。 如 果 提 供 一 个 自 定义 的 轮廓 ， 
会 覆盖 这 个 默认 的 阴影 形状 。 
以 下 方式 可 以 自 定义 视图 的 轮廓 : 


1. 继承 ViewoutlineProvider 类 
2. #5 getoutline() 函数 . 
3. 用 view.setoutlineProvider() 方法 来 设 定 视 图 的 轮廓 提供 者 . 


使 用 outline 类 的 函数 ， 你 可 以 创建 椭圆 和 带 圆 角 的 矩形 轮 廊 。 视 图 的 轮 廊 提供 者 会 从 视图 
的 背 录 中 获取 轮 廊 。 如 果 不 想 让 视图 投射 阴影 ， 你 可 以 设置 轮 廊 提 供 者 为 null。 


Clipping 视图 


Clipping 视图 (附着 视图 ， 译 者 注 ) 使 你 轻松 的 改变 视图 的 形状 。 你 可 以 为 了 一 致 性 而 附着 视 
图 ， 也 可 以 是 为 了 当 用 户 输 入 信息 时 ， 改 变 视图 的 形状 。 你 可 以 通 

过 View.setClipToOutline() 将 视图 附着 给 一 个 轮廓 或 使 用 android:clipToOutline 属性 。 只 
有 和 矩形 、 圆 形 和 圆 角 和 矩形 轮廓 支持 附着 功能 ， 你 可 以 通过 outlin.canclip() 方法 来 检查 是 否 
支持 附着 。 


把 视图 附着 给 drawable 的 形状 ， 要 将 这 个 drawable 设 置 为 视图 的 背景 ， 并 调 
用 view.setclipTooutline() 方法 。 


附着 视图 是 一 个 兄 贵 的 操作 ， 所 以 不 要 对 附着 过 的 形状 是 进行 动画 。 要 实现 这 个 效果 ， 使 用 
Reveal Effect 动画 


使 用 Drawables 


编写 : allenlsy - 原文 : https://developer.android.com/training/material/drawables.html 


使 用 Drawable 


以 下 这 些 drawable 的 功能 ， 能 帮助 你 在 应 用 中 实现 Material Design : 


e Drawable 类 色 
e 提取 主 色 调 
e 矢量 Drawable 


本 课 教 你 如 何在 应 用 中 使 用 这 些 特性 : 


给 Drawable 资源 染色 


使 用 Android 5.0 (API level 21) 以 上 版 本 ， 你 可 以 使 用 alpha mask (透明 度 图 层 ， 译 者 注 ) 给 
位 图 和 nine patches 图 片 染色 。 你 可 以 用 赢 色 Resource 或 者 主题 属性 来 获取 颜色 (比如 ，? 
android:attr/colorPrimary ) 。 通 常 ， 你 只 需要 创建 一 次 这 些 颜 色 asset， 便 可 以 在 主题 中 自 
动 匹配 这 些 颜 色 。 


你 可 以 用 setTint() 方法 将 一 种 染色 方式 应 用 到 BitmapDrawable 或 者 NinePatchDrawable 对 
Ro 你 也 在 layout 中 使 用 android:tint 和 android:initMode 属性 设置 染色 的 颜色 和 模式 。 


从 图 所 中 提取 主 色调 


Android Support Library v21 及 更 高 版 本 带 有 Palatte 类 ， 可 以 让 你 从 图 片 中 提取 主 色调 。 这 
个 类 可 以 提取 以 下 颜色 : 


e Vibrant: 亮色 

e Vibrant dark: 深 亮色 
e Vibrant light: 7X 3% & 
e Muted: 暗色 

e Muted dark: 深 暗 色 

e Muted light: 浅 暗 色 


提取 这 些 颜 色 时 ， 在 你 载 入 图 片 的 后 台 线 程 中 传 入 一 个 Bitmap 对 象 给 Palette.generate() af 
态 方法 。 如 果 你 不 能 使 用 那个 线程 ， 可 以 调用 Palatte.generateAsync() 方法 ， 并 提供 一 个 
listener ° 


你 可 以 用 Palette 类 的 一 个 getter 方 法 从 图 片 获 取 主 色调 ， 比 如 Palette.getVibrantColor() ° 


要 使 用 Palette 类 ， 在 你 的 应 用 模块 的 Gradle 依 赖 中 添加 以 下 代码 : 


dependencies { 


compile 'com.android.support:palette-v7:21.0.+' 


更 多 信息 ， 请 参见 Palette 类 的 API 文 档 。 


创建 矢量 Drawable 


Æ Android 5.0 (API level 21) 义 上 版 本 中 ， 你 可 以 定义 矢量 drawable， 用 于 无 损 的 拉 伸 图 片 。 
相对 于 一 张 普通 图 片 需要 为 每 个 不 同 屏幕 密度 的 设备 提供 一 个 图 片 来 说 ， 一 个 矢量 图 片 只 需 
要 一 个 asset 文 件 。 要 创建 矢量 图 片 ， 你 可 以 在 <vector> XML 元 素 中 定义 形状 。 


以 下 代码 定义 了 一 个 心 形 : 


<!-- res/drawable/heart.xml --> 
<vector xmlns:android="http://schemas.android.com/apk/res/android" 
<!-- intrinsic size of the drawable --> 
android:height="256dp" 
android:width="256dp" 
<!-- size of the virtual canvas --> 
android: viewportWidth="32" 
android: viewportHeight="32"> 


<!-- draw a path --> 
«path android: fillColor="#8f ff" 
android: pathData="M20.5,9.5 
c-1.955,0, -3.83,1.268, -4.5,3 
c-0.67, -1.732, -2.547, -8, -4.5, -8 
C8.957,9.5,7,11.432,7,14 
c0,3.53,3.793,6.257,9,11.5 
c5.207, -5.242,9, -7.97,9, -11.5 
C25,11.432,23.043,9.5,20.5,9.5z" /> 
</vector> 


矢量 图 片 在 Android 中 用 VectorDrawable 对 象 来 表示 。 更 多 关于 pathdata 语法 的 信息 ， 请 
看 SVG Path 的 文档 。 更 多 关于 矢量 drawable 动 画 的 信息 ， 请 参见 矢量 drawable 动 画 。 


使 用 Drawables 
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> zh 二 
目 定义 动画 
编写 : allenlsy - 原文 : https://developer.android.com/training/material/animations.html 


Material Design 中 的 动画 对 用 户 的 动作 进行 反馈 ， 并 提供 在 整个 交互 过 程 中 的 视觉 连续 性 。 
Material = 28 7j 4 42 fe Activity 4& J& HE — Xe Ri 8) 27 8 > Android 5.0 (API level 21) 及 以 上 版 
本 支持 自 定义 这 些 动画 并 创建 新 动画 : 


触摸 反馈 

圆 形 填充 
Activity 切换 动画 
曲线 形 动作 
视图 状态 变换 


ÉJ x SL AR d BC 

Material Design 中 的 触摸 反馈 ， 是 在 用 户 与 UI 元 素 交 互 时 ， 提 供 视觉 上 的 即时 确认 。 按 钮 的 
默认 触摸 反馈 动画 使 用 了 新 的 RippleDrawable 类 ， 它 在 按钮 状态 变换 时 产生 波纹 效果 。 

大 多 数 情 况 下 ， 你 需要 在 你 的 XML 文件 中 设 定 视图 的 背景 来 实现 这 个 功能 : 


e ?android:attr/selectableItemBackground 用 T AJ Ripplez? i 
e ?android:attr/selectableItemBackgroundBorderless 用 于 越 出 视图 边界 的 动画 。 它 会 被 绘 
制 在 最 近 的 且 不 是 全 屏 的 父 视图 上 。 


Note : selectableItemBackgroundBorderless Æ API level 21 新 加 入 的 属性 
另外 ， 你 可 以 使 用 ripple 元 素 在 XML 资源 文件 中 定义 一 个 RippleDrawable ° 


你 可 以 给 RippleDrawable RPA E, o BARRA E o (800 38 
的 android:colorControlHighlight 属性 。 


更 多 信息 ， 参 见 RippleDrawable 类 的 API 文 档 。 


使 用 填充 效果 (Reveal Effect) 


填充 效果 在 Ul 元 素 出 现 或 隐藏 时 ， 为 用 户 提供 视觉 连续 
性 。 viewAnimationUtils. createCircularReveal() 方法 可 以 使 用 一 个 附着 在 视图 上 的 圆 形 ， 显 
示 或 隐藏 这 个 视图 。 


要 用 此 效果 显示 一 个 原本 不 可 见 的 视图 : 


// previously invisible view 
View myView - findViewById(R.id.my view); 


// get the center for the clipping circle 
int cx = (myView.getLeft() + myView.getRight()) / 2; 
int cy = (myView.getTop() + myView.getBottom()) / 2; 


// get the final radius for the clipping circle 
int finalRadius - myView.getWidth(); 


// create and start the animator for this view 
// (the start radius is zero) 
Animator anim = 
ViewAnimationUtils.createCircularReveal(myView, cx, cy, 0, finalRadius); 
anim.start(); 


要 用 此 效果 隐藏 一 个 原本 可 见 的 视图 : 


// previously visible view 
final View myView - findViewById(R.id.my view); 


// get the center for the clipping circle 
int cx = (myView.getLeft() + myView.getRight()) / 2; 


int cy = (myView.getTop() + myView.getBottom()) / 2; 


// get the initial radius for the clipping circle 
int initialRadius - myView.getWidth(); 


// create the animation (the final radius is zero) 
Animator anim = 
ViewAnimationUtils.createCircularReveal(myView, cx, cy, initialRadius, 0); 


// make the view invisible when the animation is done 
anim.addListener(new AnimatorListenerAdapter() { 
@Override 
public void onAnimationEnd(Animator animation) { 
super .onAnimationEnd(animation) ; 
myView.setVisibility(View. INVISIBLE) ; 


3); 


// start the animation 
anim.start(); 
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B 
Material Design 中 的 Activity 切 换 ， 当 不 同 Activity 之 间 拥 有 共有 元 素 ， 则 可 以 通过 不 同 状 态 之 
间 的 动画 和 形变 提供 视觉 上 的 连续 性 。 你 可 以 为 共有 元 素 设 定 进入 和 退出 Activity 时 的 自 定义 
动画 。 


© O a, 


© 入 场 变 换 决 定 视图 如 何 入 场 。 比 如 ， 在 爆炸 式 入 场 变换 中 ， 视 图 从 场 外 飞 到 屏幕 中 央 。 

e 出 场 变 换 决 定 视图 如 何 退 出 。 比 如 ， 在 爆炸 式 出 场 变 换 中 ， 视 图 从 屏幕 中 央 飞 出 场 外 。 

e. 共有 元 素 的 变换 决定 一 个 共有 视图 在 两 个 Activity 之 间 如 何 变换 。 比 如 ， 如 果 两 个 activity 
有 同一 张 图 片 ， 但 是 放 在 不 同位 置 ， 以 及 拥有 不 同 大 小 ， 变 更 图 片 变换 会 流畅 的 把 图 片 
移 到 相应 位 置 ， 同 时 缩放 图 片 大 小 。 


Android 5.0 (API level 21) 支持 这 些 入 场 和 退出 变换 : 


o 爆炸 - 把 视图 移入 或 移出 场景 的 中 间 
e 滑动 - 把 视图 从 场景 边缘 移入 或 移出 
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e 淡 入 淡出 -通过 改变 透明 度 添 加 或 移 除 元 素 


任何 继承 于 visibility 类 的 变换 ， 都 支持 被 用 于 入 场 或 退出 变换 。 更 多 信息 ， 请 参见 
Transition 类 的 API 文 档 。 


Android 5.0 (API level 21) 还 支持 这 些 共 有 元 素 变 换 效 果 : 


e changeBounds - 对 目标 视图 的 外 边界 进行 动画 
。 chagneClipBounds - 对 目标 视图 的 附着 物 的 外 边界 进行 动画 
e changeTransform - 对 目标 视图 进行 缩放 和 旋转 
。 changelmageTransform - 对 目标 图 片 进 行 缩放 


当 你 在 应 用 中 进行 activity 变换 时 ， 默 认 的 淡 入 淡出 效果 会 被 用 在 进入 和 退出 activity 的 过 程 


Button 





Activity 1 Scene Transition Animation Activity 2 
(common element) 


自 定 义 切 换 


首先 ， 当 你 继承 Material 主 题 的 style 时 ， 要 通过 android:windowcontentTransitions 属性 来 开局 
窗口 内 容 变换 功能 。 你 也 可 以 在 style 定 义 中 声明 进入 、 退 出 和 共有 元 素 切 换 : 


«style name="BaseAppTheme" parent="android: Theme.Material"> 
<!-- enable window content transitions --> 
<item name="android:windowContentTransitions">true</item> 


<!-- specify enter and exit transitions --> 
<item name="android:windowEnterTransition">@transition/explode</item> 
<item name="android:windowExitTransition">@transition/explode</item> 


<!-- specify shared element transitions --> 
<item name="android:windowSharedElementEnterTransition"> 
@transition/change_image_transform</item> 
<item name="android:windowSharedElementExitTransition"> 
@transition/change_image_transform</item> 
</style> 


例子 中 的 change image transform 切换 定义 如 下 : 


«!-- res/transition/change image transform.xml --> 

«!-- (see also Shared Transitions below) --» 

<transitionSet xmlns:android-"http://schemas.android.com/apk/res/android"» 
<changeImageTransform/> 

</transitionSet> 


changeImageTransform 元 素 对 应 ChangeImageTransform X ° 更 多 信息 ， 请 参见 
Transition 类 的 API 文 档 。 


要 在 代码 中 局 用 窗口 内 容 切 换 ， 调 用 window.requestFeature() 函数 : 


// inside your activity (if you did not enable transitions in your theme) 
getwindow().requestFeature(Window.FEATURE CONTENT TRANSITIONS); 


// set an exit transition 
getWindow().setExitTransition(new Explode()); 


要 声明 变换 类 型 ， 就 要 在 Transition 对 象 上 调用 以 下 函数 : 


*  window.setEnterTransition() 
@  window.setExitTransition() 
*  window.setSharedElementEnterTransition() 


@  window.setSharedElementExitTransition() 


setExitTransition() 和 setSharedElementExitTransition() 岁数 为 activity 定 义 了 退出 变换 效 
Æ ° setEnterTransition() 和 setSharedElementEnterTransition() 函数 定义 了 进入 activity 的 
变换 效果 。 


要 获得 切换 的 全 部 效果 ， 你 必须 在 出 入 的 两 个 activity 中 都 开启 窗口 内 容 切换 。 否 则 ， 调 用 的 
activity 会 使 用 退出 效果 ， 但 是 接着 你 会 看 到 一 个 传统 的 窗口 切换 (比如 缩放 或 淡 入 淡出 ) © 


要 尽早 开始 入 场 切 换 ， 可 以 在 被 调用 的 Activity 上 使 
用 Window.setAllowEnterTransitionOverlap() ° 它 可 以 使 你 拥有 更 戏剧 性 的 入 场 切 换 。 


使 用 切换 启动 一 个 Activity 


如 果 你 开启 Activity 入 场 和 退出 效果 ， 那 么 当 你 在 用 如 下 方法 开始 Activity 时 ， 切 换 效 果 会 被 应 
m: 


startActivity(intent, 
ActivityOptions.makeSceneTransitionAnimation(this).toBundle()); 


如 果 你 为 第 二 个 Activity 设 定 了 入 场 变 换 ， 变 换 也 会 在 activity 开 始 时 被 启用 。 要 在 开始 另 一 个 
acitivity 时 禁用 变换 ， 可 以 给 bundle 的 选项 提供 一 个 null HH: 


启动 一 个 拥有 共用 元 素 的 Activity 
要 在 两 个 拥有 共用 元 素 的 activity 间 进行 切换 动画 : 


在 主题 中 开启 窗口 内 容 切换 

在 style 中 定义 共有 元 素 切换 

将 切换 定义 为 一 个 XML 资源 文件 

使 用 android:transitionName 属性 在 两 ^Nayoutx fF PRHALERTA-+*+EF 


使 用 ActivityOptions.makeSceneTransitionAnimation() 方法 


POD 


// get the element that receives the click event 
final View imgContainerView - findViewById(R.id.img container); 


// get the common element for the transition in this activity 
final View androidRobotView - findViewById(R.id.image small); 


// define a click listener 
imgContainerView.setOnClickListener(new View.OnClickListener() { 
QOverride 
public void onClick(View view) { 
Intent intent = new Intent(this, Activity2.class); 
// create the transition animation - the images in the layouts 
// of both activities are defined with android:transitionName-"robot" 
ActivityOptions options - ActivityOptions 
.makeSceneTransitionAnimation(this, androidRobotView, "robot"); 
// start the new activity 
startActivity(intent, options.toBundle()); 


3) 


对 于 用 代码 编写 的 共有 动态 视图 ， 使 用 view.setrransitionName() 方法 来 在 两 个 activity 中 定义 
共有 元 素 。 


要 在 第 二 个 activity 结 束 时 进行 北向 的 场景 切换 动画 ， 调 


用 Activity.finishAfterTransition() 方法 ， 而 不 是 Activity.finish() ° 


开始 一 个 拥有 多 个 共有 元 素 的 Activity 


要 在 拥有 多 个 共有 元 素 的 activity 之 间 使 用 变换 动画 ， 就 要 用 android:transitionName 属性 在 两 
个 layout 中 定义 这 个 共有 元 素 (或 在 两 个 Activity 中 使 用 View.setTransitionName() 方法 ) ， 再 
创建 Activityoptions 对 象 : 


ActivityOptions options = ActivityOptions.makeSceneTransitionAnimation(this, 
Pair.create(view1, "agreedName1"), 
Pair.create(view2, "agreedName2")); 


使 用 曲线 动画 


Material Design 中 的 动画 可 以 表示 为 基于 时 间 插 值 和 空间 移动 模式 的 曲线 。 在 Android 5.0 
(API level 21) 以 上 版 本 中 ， 你 可 以 为 动画 定义 时 间 曲 线 和 曲线 动画 模式 。 


PathInterpolator 类 是 一 个 基于 贝 泽 尔 曲线 或 Path 对 象 的 新 的 插值 方法 。 插 值 方 法 是 一 个 
定义 在 1X1 正方 形 中 的 曲线 函数 图 像 ， 其 始末 两 点 分 别 在 (0,0) 和 (1,1)， 一 个 用 构造 函数 定 
义 的 控制 点 。 你 也 可 以 使 用 XML 资源 文件 定义 一 个 插值 方法 : 


«pathInterpolator xmlns:android-"http://schemas.android.com/apk/res/android" 
android:controlX1="0.4" 
android:controlY1="0" 
android:controlX2="1" 
android:controlY2="1"/> 


Material Design 标 准 中 ， 系 统 提 供 了 三 种 基本 的 曲线 : 


e  Qinterpolator/fast out linear in.xml 
*  Qinterpolator/fast out slow in.xml 


e  Qinterpolator/linear out slow in.xml 
你 可 以 将 一 个 PathInterpolator 对 象 传 给 Animator.setInterpolator() 方法 。 


objectAnimator 类 有 一 个 新 的 构造 函数 ， 使 你 可 以 沿 一 条 路 径 使 用 多 个 属性 来 在 坐标 系 中 进 
行 变换 。 比 如 ， 以 下 animator (动画 器 ， 译 者 注 ) 使 用 一 个 path 对 象 来 改变 一 个 试图 的 X 和 Y 
属性 : 


ObjectAnimator mAnimator; 
mAnimator = ObjectAnimator.ofFloat(view, View.X, View.Y, path); 


mAnimator.start(); 


基于 视图 状态 改变 的 动画 


StatelistAnimator 类 是 你 可 以 定义 在 视图 状态 改变 启动 的 Animator (动画 器 ， 译 者 注 ) ov 
下 例子 展示 如 何在 XML 文件 中 定义 stateListAnimator 


«!-- animate the translationZ property of a view when pressed --> 
«selector xmlns:android="http://schemas.android.com/apk/res/android"> 
«item android:state_pressed="true"> 
«set» 

«objectAnimator android:propertyName-"translationZz" 
android:duration-"Qandroid:integer/config shortAnimTime" 
android:valueTo-"2dp" 
android: valueType="floatType"/> 


<!-- you could have other objectAnimator elements 
here for "x" and "y", or other properties --> 
</set> 
</item> 


<item android:state_enabled="true" 
android: state_pressed="false" 
android: state_focused="true"> 
S Seb 
«objectAnimator android:propertyName-"translationZz" 
android:duration-z"100" 
android: valueTo="0" 
android: valueType="floatType"/> 
</set> 
</item> 
</selector> 


要 把 视图 改变 Animator 关 联 到 一 个 视图 ， 就 要 在 XML 资源 文件 的 selector 元 素 上 定义 一 个 
Animator， 并 把 此 Animator 赋 值 给 视图 的 android:stateListAnimator 属性 。 要 想 在 Java 代 码 
中 将 状态 列表 Animator 赋 值 给 视图 ， 使 用 AnimationInflater.loadStateListAnimator() 函数 ， 
并 用 view.setstateListAnimator() 函数 把 Animator 赋 值 给 你 的 视图 。 


当 你 的 主题 继承 于 Material Theme 的 时 候 ，Button 默 认 会 有 一 个 Z 值 动画 。 为 了 避免 Button 的 
Z 值 动画 , 设 定 它 的 android:statelLlistAnimator 属性 为 Qnull ° 


AnimatedStateListDrawable 类 使 你 可 以 创 建 一 个 在 视图 状态 变化 之 间 显 示 动 5 4) drawable F 
有 一 些 Android 5.0 系 统 组 件 默 认 已 经 使 用 了 这 些 动画 。 下 面 的 例 展 示 如 何在 XML 资源 文件 中 
定义 AnimatedStateListDrawable : 


«!-- res/drawable/myanimstatedrawable.xml --> 
«animated-selector 
xmlns:android="http://schemas.android.com/apk/res/android"> 


<!-- provide a different drawable for each state--> 

<item android:id="@t+id/pressed" android: drawable="@drawable/drawableP" 
android:state_pressed="true"/> 

<item android:id="@+id/focused" android: drawable="@drawable/drawableF" 
android: state_focused="true"/> 

<item android:id="@id/default" 
android: drawable="@drawable/drawableD"/> 


<!-- specify a transition --> 
«transition android: fromId="@+id/default" android: toId="@+id/pressed"> 
<animation-list> 
<item android:duration="15" android: drawable="@drawable/dti"/> 
<item android:duration="15" android: drawable="@drawable/dt2"/> 


«/animation-list» 
«/transition» 


</animated-selector> 


一 


Z5 kÆ Drawables 


矢量 Drawable 是 可 以 无 损 缩放 的 。 AnimatedvectorDrawable Ž Æ% "T VAd&TE KS Drawable ° 
你 通常 在 3 个 XML 文 件 中 定义 动画 矢量 Drawable : 


e 在 res/drawable/ 中 用 <Vector> 定义 一 个 矢量 drawable 
e 在 res/drawable/ 中 用 «animated-vector» 定义 一 个 动画 矢量 drawable 
e 在 `res/anim/' 中 定义 一 个 或 多 个 Animator 


动画 矢量 drawable 可 以 用 在 «group» 和 «path» 元 素 的 属性 上 。 «group» 元 素 定 义 了 一 些 path 
或 者 subgroup * «path» 定义 了 一 条 被 绘画 的 路 径 。 


当 你 想 要 定义 一 个 动画 的 矢量 drawable 时 ， 使 用 android:name 属性 来 为 group 和 path 赋 值 一 
个 唯一 的 名 字 (name)， 这 样 你 可 以 通过 animator 的 定义 找到 他 们 。 比 如 : 


<!-- res/drawable/vectordrawable.xml --> 
«vector xmlns:android-"http://schemas.android.com/apk/res/android" 
android:height-"64dp" 
android:width="64dp" 
android: viewportHeight="600" 
android: viewportWidth="600"> 
<group 
android:name="rotationGroup" 
android: pivotX="300.0" 
android: pivotY="300.0" 
android: rotation="45.0" > 
<path 
android:name="v" 
android: fillColor="#000000" 
android: pathData="M300,70 1 0,-70 70,70 0,0 -70,70z" /> 
</group> 
</vector> 


动画 矢量 drawable 的 定义 是 通过 name 属 性 来 找到 视图 组 (group) 和 路 径 (path) 的 : 


<!-- res/drawable/animvectordrawable.xml --> 
«animated-vector xmlns:android-"http://schemas.android.com/apk/res/android" 
android:drawable-"Qdrawable/vectordrawable" > 
«target 
android:name="rotationGroup" 
android:animation="@anim/rotation" /> 
<target 
android:name="v" 
android:animation="@anim/path_morph" /> 
</animated-vector> 


动画 的 定义 代表 ObjectAnimator DE AnimatorSet Rc 4) F F 第 一 个 animator 将 目标 组 旋转 
了 360 度 。 


<!-- res/anim/rotation.xml --> 
<objectAnimator 
android: duration="6000" 
android: propertyName="rotation" 
android: valueFrom="0" 
android: valueTo="360" /> 


第 二 个 animator 将 失 量 drawable 的 路 径 从 一 个 形状 (morph) 变 形 到 另 一 个 。 两 个 路 径 都 必须 是 
可 以 形变 的 : 他 们 必须 有 相同 数量 的 命令 ， 每 个 命令 必须 有 相同 数量 的 参数 


«!-- res/anim/path morph.xml --> 
«set xmlns:android="http://schemas.android.com/apk/res/android"> 
«objectAnimator 


android:duration-"3000" 
android:propertyName-"pathData" 
android:valueFrom-"M300,70 1 0,-70 70,70 0,0 -70,70z" 
android:valueTo-"M300,70 1 0,-70 70,0 0,140 -70,0 z" 
android:valueType-"pathType" /» 

</set> 


更 多 信息 ， 请 参考 animatedvectorDrawable ) 的 API 指 南 。 
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编写 : allenlsy - 原文 : https://developer.android.com/training/material/compatibility.html 


有 些 Material Design 特 性 ， 比 如 主题 和 自 定义 Activits 切 换 效果 等 ， 只 在 Android 5.0 (API level 
21) 以 上 中 可 用 。 不 过 ， 你 仍然 可 以 使 用 这 些 特 性 实现 Material Design， 并 保持 对 昌 版 本 
Android 系统 的 兼容 。 


定义 备 选 Style 


你 可 以 配置 你 的 应 用 ， 在 支持 Material Design 的 设备 上 使 用 Material 主 题 ， 在 昌 版 本 Android 
上 使 用 中 的 主题 : 


1. 在 res/values/styles/xml 中 定义 一 个 主题 继承 自 旧 主题 (比如 Holo) 

2. 在 res/values-v21/styles.xml 中 定义 一 个 同名 的 主题 ， 继 承 自 Material 主题 

3. 在 AndroidManifest.xml 中 ， 将 这 个 主题 设置 为 应 用 的 主题 
Note: 如 果 你 的 应 用 设置 了 一 个 主题 ， 但 是 没有 提供 备 选 Style， 你 可 能 无 法 在 低 于 
Android 5.0 版 本 的 系统 中 运行 应 用 。 


提供 备 选 layout 


如 果 你 根据 Material Design 设 计 的 应 用 的 Layout 中 没有 使 用 任何 Android 5.0 (API level 21) 中 
新 的 XML 属性 ， 他 们 在 百 版 本 Android 中 就 能 正常 工作 。 和 否则 ， 你 要 提供 备 选 Layout。 你 可 以 
在 备 选 Layout 中 定义 你 的 应 用 在 昌 版 本 系统 中 的 界面 。 


在 res/layout-v21/ 中 定义 Android 5.0 (API level 21) 以 上 系统 的 Layout * Æ res/layout P Æ 
义 早 前 版 本 Android 的 Layout o 比如 ， res/layout/my activity.xml 是 对 于 res/layout- 
v21/ny activity.xml 的 一 个 备 选 Layout ° 


为 了 避免 代码 重复 ， 在 res/values 中 定义 style， 然 后 在 res/values-v21 中 修改 新 API 需 要 的 
style。 使 用 style 的 继承 ， 在 res/values/ 中 定义 父 style， 在 res/values-v21/ 中 继承 。 


使 用 Support Library 


v7 support libraries r21 及 更 高 版 本 包含 了 以 下 Material Design 特性 


e 当 你 应 用 一 个 Theme.Appcompat 主题 时 ， 会 得 到 为 一 些 系 统 控件 准备 的 Material Design 
style 


e  Theme.AppCompat 主题 包含 调 色 板 主体 属性 
e Recyclerview 组 件 用 于 显示 数据 集 

e cardview 组 件 用 于 创建 卡片 

e palette 类 用 于 从 图 片 提 取 主 色调 


系统 组 件 
Theme.AppCompat 主题 中 提供 了 这 些 组 件 的 Material Design style : 


e EditText 

e Spinner 

e CheckBox 
RadioButton 

e SwitchCompat 
CheckedTextView 


调 色 板 


要 获取 Material Design style， 并 用 v7 support library 自 定义 调 色 板 ， 就 要 应 用 以 下 中 的 一 个 
Theme.AppCompat 主 题 : 


«!-- extend one of the Theme.AppCompat themes --> 
«style name="Theme.MyTheme" parent-"Theme.AppCompat.Light"- 
<!-- customize the color palette --> 
«item name-"colorPrimary"»GQcolor/material blue 500«/item» 
«item name-"colorPrimaryDark"»Qcolor/material blue 700«/item» 
«item name-"colorAccent"»Qcolor/material green A200«/item» 
«/style» 


列表 和 卡片 


RecyclerView 和 cardview 组 件 可 通过 v7 support libraries 支 持 昌 版 本 Android， 但 有 以 下 限 
制 : 


e CardView 需 要 编程 实现 阴影 和 其 他 的 padding 
e. CardView 不 能 将 附着 与 原件 有 重合 部 分 的 子 视图 
依赖 


要 在 Android 5.0 之 前 的 版 本 使 用 这 些 特性 ， 需 要 在 项 目的 Gradle 依 赖 中 加 入 Android v7 
Support library: 


dependencies { 
compile 'com.android.support:appcompat-v7:21.0.+' 
compile 'com.android.support:cardview-v7:21.0.+' 
compile 'com.android.support:recyclerview-v7:21.0.-*' 


检查 系统 版 本 


以 下 特性 只 在 Android 5.0 (API level 21) 及 以 上 版 本 中 可 用 : 


e Activity 切换 动画 

e 触摸 反馈 

e Reveal 动画 (填充 动画 效果 ， 译 者 注 ) 
e. 基于 路 径 的 动画 

e & €drawable 

e Drawablex & 


要 保持 向 下 兼容 ， 请 在 使 用 这 些 特性 是 ， 使 用 以 下 代码 在 运行 时 检查 系统 版 本 : 


// Check if we're running on Android 5.0 or higher 

if (Build.VERSION.SDK INT >= Build.VERSION CODES.LOLLIPOP) { 
// Call some material design APIs here 

} else { 


// Implement this feature without material design 


Note: 要 声明 应 用 支持 哪些 Android 版 本 ， 在 manifest 文 件 中 使 

用 android:minsdkVersion 和 android:targetsdkVersion 属性 。 要 在 Android 5.0 中 使 用 
Material Design 特性， 设置 android:targetsdkVersion 属性 为 21。 更 多 信息 ， 参 

JL <uses-sdk> API 指 南 。 


用 户 输 入 


编写 :kesenhoo - 原文 :http://developer.android.com/training/best-user-input.html 


本 课程 涵盖 的 主题 包括 多 种 多 样 用 户 输入 ， 例 如 触摸 屏幕 手势 、 通 过 屏幕 输入 法 和 硬件 键盘 
的 文本 输入 。 


使 用 触摸 手势 
介绍 如 何 编写 允许 用 户 通过 触摸 手势 与 触摸 屏幕 进行 交互 的 app 程 序 。 


处 理 键盘 输入 事件 


介绍 在 软 输入 方法 下 〈 如 屏幕 键盘 按键 情况 下 ) 程序 的 响应 表现 和 执行 动作 ， 以 及 如 何 优化 
在 硬件 键盘 按键 下 的 用 户 体验 。 


兼容 游戏 控制 器 


介绍 如 何 编写 支持 游戏 控制 器 的 app。 


使 用 触摸 手势 


编写 :Andrwyw - 原文 :http://developer.android.com/training/gestures/index.html 


本 章节 讲述 ， 如 何 编写 一 个 允许 用 户 通过 触摸 手势 进行 交互 的 app。Android 提 供 了 各 种 各 样 
的 API， 来 帮助 我 们 创建 和 检测 手势 。 


尽管 对 于 一 些 基 本 的 操作 来 说 ， 我 们 的 app 不 应 该 依赖 于 触摸 手势 (因为 某 些 情况 下 手势 是 不 
用 的 ) 。 但 为 我 们 的 app 添 加 基于 触摸 的 交互 ， 将 会 大 大 地 提高 app 的 可 用 性 和 吸引 力 。 


为 了 给 用 户 提 供 一 致 的 、 符 合 直 觉 的 使 用 体验 ， 我 们 的 app 应 该 遵守 Android 触 摸 手 势 的 惯常 
做 法 。 手 势 设 计 指 南 介绍 了 在 Android app 中 ， 如 何 使 用 常用 的 手势 。 同 样 ， 设 计 指 南 也 提供 
了 触摸 反馈 的 相关 内 容 。 


Lessons 


令 测 常用 的 手势 

学 习 如 何 通 过 使 用 GestureDetector 来 检测 基本 的 触摸 手势 ， 如 滑动 、 惯 性 滑动 以 及 双击 。 
追踪 手势 移动 

学 习 如 何 追 踪 手 势 移动 。 

Scroll 手 势 动画 

学 习 如 何 使 用 scrollers (Scrollers 以 及 OverScroll) 来 产生 滚动 动画 ， 以 响应 触摸 事件 。 
处 理 多 触摸 手势 

学 习 如 何 检测 多 点 (手指 ) 触 摸 手势 。 

拖 搜 与 缩放 

学 习 如 何 实现 基于 触摸 的 拖 搜 与 缩放 。 

管理 ViewGroup 中 的 触摸 事件 


学 习 如 何在 ViewGroup 中 管理 触摸 事件 ， 以 确保 事件 能 被 正确 地 分 发 到 目标 views 上 。 


检测 常用 的 手势 


编写 :Andrwyw - 原文 :http://developer.android.com/training/gestures/detector.html 


当 用 户 把 用 一 根 或 多 根 手指 放 在 触摸屏 上 ， 并 且 应 用 把 这 样 的 触摸 方式 解释 为 特定 的 手势 
时 ，“ 触 摸 手 势 "就 发 生 了 。 相 应 地 ， 检 测 手势 也 就 有 以 下 两 个 阶段 : 


1. 收集 触摸 事件 的 相关 数据 。 
2. 分 析 这 些 数据 ， 看 它们 是 否 符合 app 所 支持 的 手势 的 标准 。 


Support Library 中 的 类 


本 节 课 程 的 示例 程序 使 用 了 GestureDetectorCompat 和 MotionEventCompat 类 。 这 些 类 都 是 在 
Support Library 中 定义 的 。 如 果 有 可 能 的 情况 话 ， 我 们 应 该 使 用 Support Library 中 的 类 ， 来 
为 运行 着 Android1.6 及 以 上 版 本 系统 的 设备 提供 兼容 性 功能 。 需 要 注意 的 一 点 

是 ， WA Ea T E dM M Md > 而 是 提供 了 一 些 静 态 工具 类 函数 。 我 
们 可 以 把 MotionEvent 对 象 作 为 参数 传递 给 这 些 工具 类 函数 ， 来 获得 与 触摸 事件 相关 的 动作 
(action) » 


收集 数据 


当 用 户 把 用 一 根 或 多 根 手指 放 在 触摸 屏 上 时 ， 会 触发 View 上 用 于 接收 触摸 事件 的 
onTouchEvent() 回调 函数 。 对 于 一 系列 连续 的 、 最 终 会 被 识别 为 一 种 手势 的 触摸 事件 〈 位 
置 、 压 力 、 大 小 、 添 加 另 一 根 手指 等 等 ) ，onTouchEvent() 会 被 调用 若干 次 。 


当 用 户 第 一 次 触摸 屏幕 时 ， 手 势 就 开始 了 。 其 后 系统 会 持续 地 追踪 用 户 手指 的 位 置 ， 在 用 户 
手指 全 都 离开 屏幕 时 ， 手 势 结束 。 在 整 间 ， 被 分 发 给 onTouchEvent() 4k 49 
MotionEvent 对 象 ， 提 供 了 每 次 交互 的 详细 信息 。 我 们 的 app 可 以 使 用 MotionEvent 提供 的 这 
些 数据 ， 来 判断 某 种 特定 的 手势 是 否 发 生 了 。 


为 Activity 或 View 捕 获 触摸 事件 


为 了 捕获 Activity 或 View 中 的 触摸 事件 ， 我 们 可 以 重 写 onTouchEvent() 回 调 函 数 。 


接 下 来 的 代码 段 使 用 了 getActionMasked() 函 数 ， 来 从 event 参数 中 抽取 出 用 户 执行 的 动 
作 。 它 提供 了 一 些 原始 的 触摸 数据 ， 我 们 可 以 使 用 这 些 数据 ， 来 判断 某 个 特定 手势 是 否 发 生 
Y o 


public class MainActivity extends Activity { 


// This example shows an Activity, but you would use the same approach if 
// you were subclassing a View. 

@Override 

public boolean onTouchEvent(MotionEvent event) { 


int action - MotionEventCompat.getActionMasked(event); 


switch(action) { 
case (MotionEvent.ACTION DOWN) 
Log.d(DEBUG TAG, Action was DOWN"); 
ketürnn enue, 

case (MotionEvent.ACTION_MOVE) 
Log.d(DEBUG TAG, "Action was MOVE"); 
retürnm true; 

case (MotionEvent.ACTION UP) 
Log.d(DEBUG TAG, "Action was UP"); 
return true; 

case (MotionEvent.ACTION CANCEL) 
Log.d(DEBUG TAG, Action was CANCEL"); 
return true, 

case (MotionEvent.ACTION OUTSIDE) 
Log.d(DEBUG TAG, "Movement occurred outside bounds " + 

"of current screen element"); 

retürn true; 

default : 
return super.onTouchEvent(event); 


然后 ， 我 们 可 以 对 这 些 事件 做 些 自己 的 处 理 ， 以 判断 某 个 手势 是 否 出 现 了 。 这 种 是 针对 自 定 
义 手 势 ， 我 们 所 需要 进行 的 处 理 。 然 而 ， 如 果 我 们 的 app 仅 仅 需 要 一 些 常 见 的 手势 ， 如 双击 ， 
长 按 ， 快 速 滑动 (fling) 等 ， 那 么 我 们 可 以 使 用 GestureDetector 类 来 完成 。 GestureDetector 
可 以 让 我 们 简单 地 检测 常见 手势 ， 并 且 无 需 自 行 处 理 单个 触摸 事件 。 相 关内 容 将 会 在 下 面 的 
令 测 手势 中 讨论 。 


捕获 单个 view 的 触摸 事件 


作为 onTouchEvent() 的 一 种 替换 方式 ， 我 们 也 可 以 使 用 setOnTouchListener() 函数 ， 来 把 
View.OnTouchListener 关联 到 任意 的 View 上 。 这样 可 以 在 不 继承 已 有 的 View 的 情况 下 ， 也 
能 监听 触摸 事件 。 比 如 : 


View myView = findViewById(R.id.my view); 
myView.setOnTouchListener(new OnTouchListener() ( 
public boolean onTouch(View v, MotionEvent event) { 
// ... Respond to touch events 
return true 


} 
3); 


创建 listener 对 象 时 ， 注 意 ACTION. DOWN 事件 返回 false 的 情况 。 如 果 返 回 false > S 
让 listener 对 象 接收 不 到 后 续 的 ACTION_MOVE、ACTION_UP 等 系列 事件 。 这 是 因 
为 ACTION_DOWN 事 件 是 所 有 触摸 事件 的 开端 。 


如 果 我 们 正在 写 一 个 自 定 义 View， 我 们 也 可 以 像 上 面 描述 的 那样 重 写 onTouchEvent() 函 数 。 


gr» T 


Android 提 供 了 GestureDetector 类 来 检测 常用 的 手势 。 它 所 支持 的 手势 包括 
onDown() ` onLongPress() ` onFling() 等 。 我 们 可 以 把 GestureDetector 和 上 面 描述 的 
onTouchEvent() 函 数 结合 在 一 起 使 用 。 


测 所 有 支持 的 手势 


当 我 们 实例 化 一 个 GestureDetectorCompat 对 象 时 ， 需 要 一 个 实现 了 
GestureDetector.OnGestureListener 接 口 的 类 作为 参数 。 当 某 个 特定 的 触摸 事件 发 生 

时 ，GestureDetector.OnGestureListener 就 会 通知 用 户 。 为 了 让 我 们 的 GestureDetector 对 象 
能 到 接收 到 触摸 事件 ， 我 们 需要 重 写 View X Activity 的 onTouchEvent() 函数 ， 并 且 把 所 有 
捕获 到 的 事件 传递 给 detector 实例 。 


接 下 来 的 代码 段 中 ， on<TouchEvent> 型 的 元 数 的 返回 值 是 true ， 意 味 着 我 们 已 经 处 理 完 这 
个 触摸 事件 了 。 如 果 返 回 false ， 则 会 把 事件 沿 view 栈 传递 ， 直 到 触摸 事件 被 成 功 地 处 理 
To 


运行 下 面 的 代码 段 ， 来 了 解 当 我 们 与 触摸 屏 交 互 时 ， 动 作 (action) 是 如 何 触 发 的 ， 以 及 每 个 
触摸 事件 MotionEvent 中 的 内 容 。 我 们 也 会 意识 到 ， 一 个 简单 的 交互 会 产生 多 少 的 数据 。 


public class MainActivity extends Activity implements 
GestureDetector.OnGestureListener, 
GestureDetector.OnDoubleTapListener{ 


private static final String DEBUG_TAG = "Gestures"; 
private GestureDetectorCompat mDetector; 


// Called when the activity is first created. 
@Override 








public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity main); 
// Instantiate the gesture detector with the 
// application context and an implementation of 
// GestureDetector.OnGestureListener 
mDetector - new GestureDetectorCompat(this,this); 
// Set the gesture detector as the double tap 
// XXstener. 
mDetector.setOnDoubleTapListener(this); 


@Override 

public boolean onTouchEvent(MotionEvent event){ 
this.mDetector.onTouchEvent(event); 
// Be sure to call the superclass implementation 
return super.onTouchEvent(event); 


@Override 

public boolean onDown(MotionEvent event) { 
Log.d(DEBUG TAG, "onDown: ”+ event.toString()); 
return true; 


@Override 
public boolean onFling(MotionEvent event1, MotionEvent event2, 
float velocityX, float velocityY) 1 
Log.d(DEBUG TAG, "onFling: " + eventi.toString()-*event2.toString()); 
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@Override 
public void onLongPress(MotionEvent event) { 
Log.d(DEBUG_TAG, "onLongPress: " + event.toString()); 


@Override 
public boolean onScroll(MotionEvent ei, MotionEvent e2, float distancex, 
float distanceY) ( 
Log.d(DEBUG TAG, "onScroll: " + e1.toString()+e2.toString()); 
return true; 


@Override 
public void onShowPress(MotionEvent event) { 
Log.d(DEBUG TAG, "onShowPress: " + event.toString()); 


@Override 

public boolean onSingleTapUp(MotionEvent event) ( 
Log.d(DEBUG TAG, "onSingleTapUp: " + event.toString()); 
recurnm Enue, 
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} 


@Override 

public boolean onDoubleTap(MotionEvent event) { 
Log.d(DEBUG TAG, "onDoubleTap: " + event.toString()); 
fe tunt Ue 


} 


@Override 

public boolean onDoubleTapEvent(MotionEvent event) { 
Log.d(DEBUG TAG, "onDoubleTapEvent: " + event.toString()); 
return true; 


} 


@Override 

public boolean onSingleTapConfirmed(MotionEvent event) { 
Log.d(DEBUG TAG, "onSingleTapConfirmed: " + event.toString()); 
FEEURN tn ue, 


会 测 部 分 支持 的 手势 


如 果 我 们 只 想 处 理 几 种 手势 ， 那 么 可 以 选择 继承 GestureDetector.SimpleOnGestureListener 
类 ， 而 不 是 实现 GestureDetector.OnGestureListener 接口 。 


GestureDetector.SimpleOnGestureListener 类 实现 了 所 有 的 on<TouchEvent> AE > H 

中 ， 这 些 函数 都 返回 false 。 因 此 ， 我 们 可 以 仅仅 重 写 我 们 需要 的 函数 。 比 如 ， 下 面 的 代码 
段 中 ， 创 建 了 一 个 继承 自 GestureDetector.SimpleOnGestureListener 的 类 ， 并 重 写 了 
onFling() 和 onDown() 函数 。 


无 论 我 们 是 否 使 用 GestureDetector.OnGestureListener 类 ， 最 好 都 实现 onDown() 函数 并 且 返 
E] true 。 这 是 因为 所 有 的 手势 都 是 由 onDown() 消息 开始 的 。 如 果 让 onDown() 函数 返回 
false ， 就 像 GestureDetector.SimpleOnGestureListener 类 中 默认 实现 的 那样 ， 系 统 会 假定 
我 们 想 忽 略 剩余 的 手势 ，GestureDetector.OnGestureListener 中 的 其 他 函数 也 就 永远 不 会 被 
调用 。 这 可 能 会 导致 我 们 的 app 出 现 意 想不到 的 问题 。 仅 仅 当 我 们 丨 的 想 忽 略 全 部 手势 时 ， 我 
们 才 应 该 让 onDown() 函数 返回 false ° 


public class MainActivity extends Activity { 


private GestureDetectorCompat mDetector; 


@Override 

public void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity main); 
mDetector - new GestureDetectorCompat(this, new MyGestureListener()); 


@Override 

public boolean onTouchEvent(MotionEvent event) { 
this.mDetector.onTouchEvent(event); 
return super.onTouchEvent(event); 


class MyGestureListener extends GestureDetector.SimpleOnGestureListener { 
private static final String DEBUG_TAG = "Gestures"; 


@Override 

public boolean onDown(MotionEvent event) { 
Log.d(DEBUG TAG, "onDown: ”+ event.toString()); 
return true; 


@Override 
public boolean onFling(MotionEvent eventi, MotionEvent event2, 
float velocityX, float velocityY) { 
Log.d(DEBUG TAG, "onFling: " + eventi.toString()*event2.toString()); 
return true; 


追踪 手势 移动 


编写 :Andrwyw - 原文 : http://developer.android.com/training/gestures/movement.html 
本 节 课 程 讲述 如 何 追 踪 手 势 移动 。 


每 当当 前 的 触摸 位 置 、 压 力 、 大 小 发 生变 化 时 ，ACTION_MOVE 事 件 都 会 触发 
onTouchEvent() 元 数 。 正 如 检测 常用 的 手势 中 描述 的 那样 ， 触 摸 事件 全 部 都 记录 在 
onTouchEvent() 函 数 的 MotionEvent 参 数 中 。 


因为 基于 手指 的 触摸 的 交互 方式 并 不 总 是 非常 精确 ， 所 以 检测 触摸 事件 更 多 的 是 基于 手势 移 
动 ， 而 非 简单 地 基于 触摸 。 为 了 帮助 app 区 分 基于 移动 的 手势 (如 滑动 ) 和 非 移动 手势 (如 简 
单 地 点 击 ) > Androids] A T “touch slop” 的 概念 。Touch slop 是 指 ， 在 被 识别 为 基于 移动 的 手 
势 前 ， 用 户 触摸 可 移动 的 那 一 段 像素 距离 。 关 于 这 一 主题 的 更 多 讨论 ， 可 以 在 管理 ViewGroup 
中 的 触摸 事件 中 查看 。 


根据 应 用 的 需求 ， 有 多 种 追踪 手势 移动 的 方式 可 以 选择 。 比 如 : 


e 追踪 手指 的 起 始 和 终止 位 置 (比如 ， 把 屏幕 上 的 对 象 从 A 点 移动 到 B 点 ) 

e 根据 x、y 轴 坐标 ， 追 踪 手 指 移动 的 方向 。 

e 追踪 历史 状态 。 我 们 可 以 通过 调用 MotionEvent 的 getHistorySize() 方 法 ， 来 获得 一 个 手势 
的 历史 尺寸 。 我 们 可 以 通过 移动 事件 的 getHistoricalevalue» 系列 函数 ， 来 获得 事件 之 前 
的 位 置 、 尺 寸 、 时 间 以 及 按压 力 (pressures)。 当 我 们 需要 绘制 用 户 手指 痕迹 时 ， 历 史 状 
态 非常 有 用 ， 比 如 触摸 绘图 。 查 看 MotionEvent 来 了 解 更 多 细节 。 

e 追踪 手指 在 触摸 屏 上 滑 过 的 速度 


追踪 速度 


我 们 可 以 简单 地 用 基于 距离 ， 或 (和 ) 基 于 手指 移动 方向 的 移动 手势 。 但 是 速度 经 党 tig 
势 特性 的 一 个 决定 性 因素 ， 基 至 是 判断 一 个 手势 是 否 发 生 的 依据 。 为 了 让 计算 速度 na 
ces 了 VelocityTracker 类 以 及 Support Library ¥ &) VelocityTrackerCompat 

。 VelocityTracker 类 可 以 帮 sao 追踪 触摸 事件 中 的 速度 因素 。 如 果 速 度 是 手势 的 一 个 判断 
， 比 如 快速 滑动 (fing)， 那 么 这 些 类 是 很 有 用 的 。 


下 面 是 一 个 简单 的 例子 ， 说 明了 VelocityTracker 中 APIl 亟 数 的 用 处 。 


public class MainActivity extends Activity { 
private static final String DEBUG TAG - "Velocity"; 


private VelocityTracker mVelocityTracker - null; 
@Override 
public boolean onTouchEvent(MotionEvent event) { 
int index - event.getActionIndex(); 
int action = event.getActionMasked(); 
int pointerId = event.getPointerId(index); 


switch(action) { 
case MotionEvent.ACTION DOWN: 
if(mVelocityTracker == null) { 
// Retrieve a new VelocityTracker object to watch the velocity of 
a motion. 
mVelocityTracker - VelocityTracker.obtain(); 
} 
else f 
// Reset the velocity tracker back to its initial state. 
mVelocityTracker.clear(); 

} 

// Add a user's movement to the tracker. 

mVelocityTracker .addMovement (event); 

break; 

case MotionEvent.ACTION MOVE: 
mVelocityTracker.addMovement(event); 

// When you want to determine the velocity, call 

// computeCurrentVelocity(). Then call getXVelocity() 

// and getYVelocity() to retrieve the velocity for each pointer ID. 

mVelocityTracker.computeCurrentVelocity(1000); 

// Log velocity of pixels per second 

// Best practice to use VelocityTrackerCompat where possible. 

Log.d("", "X velocity: " + 
VelocityTrackerCompat.getXVelocity(mVelocityTracker, 
pointerId)); 

BogRd( VAVE Loc IY east 
VelocityTrackerCompat.getYVelocity(mVelocityTracker, 
pointerId)); 

break; 

case MotionEvent.ACTION UP: 
case MotionEvent.ACTION CANCEL: 

// Return a VelocityTracker object back to be re-used by others. 

mVelocityTracker.recycle(); 

break; 


j 
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Note: 需要 注意 的 是 ， 我 们 应 该 在 ACTION_MOVE 事 件 ， 而 不 是 在 ACTION_UP 事 件 后 
计算 速度 。 在 ACTION_UP 事 件 之 后 ， 计 算 xX、y 方 向 上 的 速度 都 会 是 0 。 


跟踪 手势 移动 
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US I d NEST 
RON $ 势 动画 
编写 :Andrwyw - 原文 :http://developer.android.com/training/gestures/scroll.html 


在 Android 中 ， 通 常 使 用 ScrollView 类 来 实现 滚动 (scroll) 。 任 何 可 能 超过 父 类 边界 的 布局 ， 
都 应 该 诅 套 在 ScrollView 中 ， 来 提供 一 个 由 系统 框架 管理 的 可 滚动 的 view。 仅 在 某 些 特殊 情形 
下 ， 我 们 才 要 实现 一 个 自 定义 scroller。 本 节 课 程 就 描述 了 这 样 一 个 情形 : 使 用 scrollers 显示 
滚动 效果 ， 以 响应 触摸 手势 。 


为 了 收集 数据 来 产生 滚动 动画 ， 以 响应 一 个 触摸 事件 ， 我 们 可 以 使 用 scrollers (Scroller 或 
者 OverScroller) 。 这 两 个 类 很 相似 ， 但 OverScroller 有 一 些 函 数 ， 能 在 平移 或 快速 滑动 手势 
后 ， 向 用 户 指出 已 经 达到 内 容 的 边缘 。 Interactivechart 例子 使 用 了 EdgeEffect 类 (实际 上 
是 EdgeEffectCompat 类 ) ， 在 用 户 到 达 内 容 的 边缘 时 显示 "发光" 效果。 


Note: 比 起 Scroller 类 ， 我 们 更 推荐 使 用 OverScroller 类 来 产生 滚动 动画 。OverScroller 类 
为 老 设 备 提供 了 很 好 的 向 后 兼容 性 。 另外 需要 注意 的 是 ， 仅 当 我 们 要 自己 实现 滚动 时 ， 
T F X4& A scrollers » 4 4114878 Ay X FE ScrollView £e HorizontalScrollView T > €11] 
会 帮 有 我 们 把 这 些 做 好 。 


通过 使 用 平台 标准 的 滚动 物理 因素 (摩擦 、 速 度 等 ) ，scroller 被 用 来 随 着 时 间 的 推移 产生 滚 
动 动画 。 实 际 上 ，scroller 本 身 不 会 绘制 任何 东西 。Scrollers 只 是 随 着 时 间 的 推移 ， 追 踪 滚动 
的 偏 移 量 ， 但 它们 不 会 自动 地 把 这 些 位 置 应 用 到 view 上 。 我 们 应 该 按 一 定 频率 ， 获 取 并 应 用 
这 些 新 的 坐标 值 ， 来 让 滚动 动画 更 加 顺 滑 。 


理解 滚动 术语 
在 Android 中 ，“Scrolling” 这 个 词根 据 不 同情 景 有 着 不 同 的 含义 。 


RA (Scrolling) 是 指 移动 视窗 (viewport) 〈 指 你 正在 看 的 内 容 所 在 的 ' 窗 口 ') 的 一 般 过 
程 。 当 在 X 轴 和 y 轴 方向 同时 滚动 时 ， 就 叫做 平移 (panning) 。 示 例 程序 提供 的 
Interactivechart 类 ， 展 示 了 两 种 不 同类 型 的 滚动 ， 拖 搜 与 快速 滑动 。 


e 444% (dragging) 是 滚动 的 一 种 类 型 ， 当 用 户 在 触摸 屏 上 拖 动 手指 时 发 生 。 简 单 的 拖 搜 一 
般 可 以 通过 重 写 GestureDetector.OnGestureListener 的 onScroll() 来 实现 。 关 于 拖 搜 的 
更 多 讨论 ， 可 以 查看 拖 搜 与 缩放 章节 。 

e 快速 滑动 (fling) 这 种 类 型 的 滚动 ， 在 用 户 快速 拖 搜 后 ， 抬 起 手指 时 发 生 。 当 用 户 抬 起 手 
指 后 ， 我 们 通常 想 继续 保持 滚动 《移动 视窗 ) ， 但 会 一 直 减 速 直到 视窗 停止 移动 。 通 过 
重 写 GestureDetector.OnGestureListener 的 onFling() 函 数 ， 使 用 scroller 对 象 ， 可 实现 快 
速 滑动 。 这 种 用 法 也 就 是 本 节 课 程 的 主题 。 


scroller 对 象 通常 会 与 快速 滑动 手势 结合 起 来 使 用 。 但 在 任何 我 们 想 让 UI 展 示 滚 动 动 画 ， 以 响 
应 触摸 事件 的 场景 ， 都 可 以 用 scroller 对 象 来 实现 。 上 比如， 我 们 可 以 重 写 onTouchEvent() 远 
数 ， 直 接 处 理 触 摸 事 件 ， 并 且 产 生 一 个 滚动 效果 或 “页 面 对 齐 ”动画 (snapping to page)， 来 响 
应 这 些 触摸 事件 。 


实现 基于 触摸 的 滚动 


本 节 讲 述 如 何 使 用 scroller。 下 面 的 代码 段 来 自 Interactivechart 示例 。 它 使 

用 GestureDetector， 并 且 重 写 了 GestureDetector SimpleOnGestureListener 的 onFling() & 
数 。 它 使 用 OverScroller 追 踪 快速 滑动 (fling) 手势 。 快 速 滑动 手势 后 ， 如 果 用 户 到 达 内 容 边 
缘 ， 应 用 会 显示 一 种 发 光 效 果 。 


Note: interactivechart 示例 程序 展示 了 一 个 可 缩放 、 平 移 、 滑 动 的 表格 。 在 接 下 来 的 
代码 段 中 ， mcontentRect 表示 View 中 的 一 块 矩 形 坐 标 区 域 ， 该 区 域 将 被 用 来 绘制 表格 。 
在 任意 给 定 的 时 间 点 ， 表 格 中 某 一 部 分 会 被 绘制 在 这 个 区 域内 。 mcurrentviewport 表示 
当前 在 屏幕 上 可 见 的 那 一 部 分 表格 。 因 为 像素 偏 移 量 通常 当 作 整 型 处 理 ， 所 

以 mContentRect 是 Rect 类 型 的 。 因 为 图 表 的 区 域 范围 是 数值 型 / 浮 点 型 值 ， 所 


以 mcurrentViewport 是 RectF 类 型 。 


代码 段 的 第 一 部 分 展示 了 onlin) 函数 的 实现 : 


// The current viewport. This rectangle represents the currently visible 
// chart domain and range. The viewport is the part of the app that the 
// user manipulates via touch gestures. 
private RectF mCurrentViewport = 

new RectF(AXIS X MIN, AXIS Y MIN, AXIS X MAX, AXIS Y MAX); 


// The current destination rectangle (in pixel coordinates) into which the 
// chart data should be drawn. 
private Rect mContentRect; 


private OverScroller mScroller; 
private RectF mScrollerStartViewport; 


private final GestureDetector.SimpleOnGestureListener mGestureListener 

= new GestureDetector.SimpleOnGestureListener() { 

@Override 

public boolean onDown(MotionEvent e) { 
// Initiates the decay phase of any active edge effects. 
releaseEdgeEffects(); 
mScrollerStartViewport.set(mCurrentViewport); 
// Aborts any active scroll animations and invalidates. 
mScroller.forceFinished(true); 
ViewCompat .postInvalidateOnAnimation(InteractiveLineGraphView. this); 
recurn ue 


NO 


@Override 
public boolean onFling(MotionEvent e1, MotionEvent e2, 
float velocityX, float velocityY) 1 
fling((int) -velocityX, (int) -velocityY); 
return tnue, 


}; 


private void fling(int velocityX, int velocityY) 1 
// Initiates the decay phase of any active edge effects. 
releaseEdgeEffects(); 
// Flings use math in pixels (as opposed to math based on the viewport). 
Point surfaceSize - computeScrollSurfaceSize(); 
mScrollerStartViewport.set(mCurrentViewport); 
int startX - (int) (surfaceSize.x * (mScrollerStartViewport.left - 
AXIS X MIN) / ( 
AXIS X MAX - AXIS X MIN)); 
int startY - (int) (surfaceSize.y * (AXIS Y MAX - 
mScrollerStartViewport.bottom) / ( 
AXIS Y MAX - AXIS Y MIN)); 
// Before flinging, aborts the current animation. 
mScroller.forceFinished(true); 
// Begins the animation 
mScroller.fling( 
// Current scroll position 
startX, 
startY, 
velocityX, 
velocityY, 
/* 
* Minimum and maximum scroll positions. The minimum scroll 
* position is generally zero and the maximum scroll position 
* is generally the content size less the screen size. So if the 
* content width is 1000 pixels and the screen width is 200 
* pixels, the maximum scroll offset should be 800 pixels. 
f 
0, surfaceSize.x - mContentRect.width(), 
0, surfaceSize.y - mContentRect.height(), 
// The edges of the content. This comes into play when using 
// the EdgeEffect class to draw "glow" overlays. 
mContentRect.width() / 2, 
mContentRect.height() / 2); 
// Invalidates to trigger computeScroll() 
ViewCompat.postInvalidateOnAnimation(this); 


3 onFling() 9&3X37H/f postInvalidateOnAnimation()Hl > € ef X computeScroll()k 3 31x » y 
的 值 。 通 常 一 个 子 view 用 scroller 对 象 来 产生 滚动 动画 时 会 这 样 做 ， 就 像 本 例 一 样 。 


大 多 数 views 直 接 通 过 scrollTo() 有 函数 传递 scroller 对 象 的 xXx、y 坐 标 值 。 接 下 来 

的 computescroll() 函数 的 实现 中 采用 了 一 种 不 同 的 方式 。 它 调用 computeScrollOffset() 有 函数 
来 获得 当前 位 置 的 x、y 值 。 当 满足 边缘 显示 发 光 效果 的 条 件 时 (图 表 已 被 放大 显示 ，X 或 y 值 
超过 边界 ， 并 且 app 当 前 没有 显示 overscroll) ， 这 段 代 码 会 设置 verscroll 发 光 效 果 ， 并 调 
用 postInvalidateonAnimation() 函数 来 让 View 失效 重 绘 : 


// Edge effect / overscroll tracking objects. 
private EdgeEffectCompat mEdgeEffectTop; 
private EdgeEffectCompat mEdgeEffectBottom; 
private EdgeEffectCompat mEdgeEffectLeft; 
private EdgeEffectCompat mEdgeEffectRight; 


private boolean mEdgeEffectTopActive; 
private boolean mEdgeEffectBottomActive; 
private boolean mEdgeEffectLeftActive; 
private boolean mEdgeEffectRightActive; 


@Override 
public void computeScroll() { 
super.computeScroll(); 


boolean needsInvalidate - false; 


// The scroller isn't finished, meaning a fling or programmatic pan 
// operation is currently active. 
if (mScroller.computeScrolloffset()) 1 

Point surfaceSize - computeScrollSurfaceSize(); 

int currX - mScroller.getCurrX(); 

int currY - mScroller.getCurrY(); 


boolean canScrollX - (mCurrentViewport.left » AXIS X MIN 
|| mCurrentViewport.right « AXIS X MAX); 

boolean canScrollY - (mCurrentViewport.top » AXIS Y MIN 
|| mCurrentViewport.bottom < AXIS Y MAX); 


/* 
If you are zoomed in and currX or currY is 
outside of bounds and you're not already 
* showing overscroll, then render the overscroll 
* glow edge effect. 
SWA 
if (canScrollx 
&& currX < 0 
&& mEdgeEffectLeft.isFinished() 
&& !mEdgeEffectLeftActive) { 
mEdgeEffectLeft.onAbsorb((int) 
OverScrollerCompat.getCurrVelocity(mScroller)); 
mEdgeEffectLeftActive - true; 
needsInvalidate - true; 
} else if (canScrollx 
&& currX » (surfaceSize.x - mContentRect.width()) 


&& mEdgeEffectRight.isFinished() 
&& !mEdgeEffectRightActive) { 
mEdgeEffectRight.onAbsorb((int) 
OverScrollerCompat.getCurrVelocity(mScroller)); 
mEdgeEffectRightActive - true; 
needsInvalidate - true; 


if (canScrollY 
&& currY < 0 
&& mEdgeEffectTop.isFinished() 
&& !mEdgeEffectTopActive) { 
mEdgeEffectTop.onAbsorb((int) 
OverScrollerCompat.getCurrVelocity(mScroller)); 
mEdgeEffectTopActive - true; 
needsInvalidate - true; 
} else if (canScrollY 
&& currY » (surfaceSize.y - mContentRect.height()) 
&& mEdgeEffectBottom.isFinished() 
&& !mEdgeEffectBottomActive) { 
mEdgeEffectBottom.onAbsorb((int) 
OverScrollerCompat.getCurrVelocity(mScroller)); 
mEdgeEffectBottomActive - true; 
needsInvalidate - true; 


// Custom object that is functionally similar to Scroller 
Zoomer mZoomer; 
private PointF mZoomFocalPoint = new PointF(); 


// If a zoom is in progress (either programmatically or via double 
// touch), performs the zoom. 
if (mZoomer.computeZoom()) { 
float newwidth = (if - mZoomer.getCurrZoom()) * 
mScrollerStartViewport.width(); 
float newHeight = (if - mZoomer.getCurrZoom()) * 
mScrollerStartViewport.height(); 
float pointWithinViewportX = (mZoomFocalPoint.x - 
mScrollerStartViewport.left) 
/ mScrollerStartViewport.width(); 
float pointWithinViewportY = (mZoomFocalPoint.y - 
mScrollerStartViewport.top) 
/ mScrollerStartViewport.height(); 
mCurrentViewport.set( 


mZoomFocalPoint.x - newwidth * pointWithinViewportx, 
mZoomFocalPoint.y - newHeight * pointWithinViewportY, 
mZoomFocalPoint.x + newWidth * (1 - pointwithinViewportX), 
mZoomFocalPoint.y + newHeight * (1 - pointWithinViewportY)); 


constrainViewport(); 
needsInvalidate = true; 


} 


if (needsInvalidate) { 


ViewCompat .postInvalidate0nAnimation(this); 


这 是 上 面 代 码 段 中 调用 过 的 computeScrollsurfaceSize() 函数 。 它 会 以 像素 为 单位 计算 3j 前 可 
滚动 的 尺寸 。 举 例 来 说 ， 如 果 整 个 图 表 区 域 都 是 可 见 的 ， 它 的 值 就 简单 地 等 

于 mcontentRect 的 大 小 。 如 果 图 表 在 两 个 方向 上 都 放大 到 200%， 此 函数 返回 的 尺寸 在 水 平 、 
重 直 方向 上 都 会 大 两 倍 。 


private Point computeScrollSurfaceSize() { 
return new Point( 
(int) (mContentRect.width() * (AXIS X MAX - AXIS X MIN) 
/ mCurrentViewport.width()), 
(int) (mContentRect.height() * (AXIS Y MAX - AXIS Y MIN) 
/ mCurrentViewport.height())); 


关于 scroller 用 法 的 另 一 个 示例 ， 可 查看 ViewPager 类 的 源 代码 。 它 用 滚动 来 响应 快速 滑动 
(fling) ， 并 且 使 用 滚动 来 实现 “页 面 对 齐 "(snapping to page) 动 画 。 
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处 理 多 点 触 控 手 势 


编写 :Andrwyw - 原文 :http://developer.android.com/training/gestures/multi.html 


多 点 触 控 手势 是 指 在 同一 时 间 有 多 点 (GB) 触 碰 屏 幕 。 本 节 课 程 讲述 ， 如 何 检 测 涉及 多 点 
的 触摸 手势 。 


追踪 多 点 


5$ 


个 手指 同时 触摸 屏幕 时 ， 系 统 会 产生 如 下 的 触摸 事件 : 


ACTION. DOWN - 针对 触摸 屏幕 的 第 一 个 点 。 此 事件 是 手势 的 开端 ? 第 一 触摸 点 的 数据 
在 MotionEvent 中 的 索引 总 是 0。 

ACTION POINTER DOWN - 针对 第 一 点 后 ， 出 现在 屏幕 上 额外 的 点 。 这 个 点 的 数据 在 
MotionEvent 中 的 索引 ， 可 以 通过 getActionIndex() 获 得 。 
ACTION_MOVE - 在 按 下 手势 期 间 发 生变 化 。 

ACTION POINTER UP - 当 非 主要 点 (non-primary pointer) 离开 屏幕 时 ， 发 送 此 事 
件 。 

ACTION UP - 当 最 后 一 点 离开 屏幕 时 发 送 此 事件 。 


我 们 可 以 通过 各 个 点 的 索引 以 及 id， 单 独 地 追踪 MotionEvent 中 的 每 个 点 。 


Index : MotionEvent 把 各 个 点 的 信息 都 存储 在 一 个 数组 中 。 点 的 索引 值 就 是 它 在 数组 中 
的 位 置 。 大 多 数 用 来 与 点 交互 的 MotionEvent 有 函数 都 是 以 索引 值 而 不 是 点 的 ID 作为 参数 
的 。 


e ID: 每 个 点 也 都 有 一 个 ID 映射 ， 该 ID 映射 在 整个 手势 期 间 一 直 存 在 ， 以 便 我 们 单独 地 追 


踪 每 个 点 。 


每 个 独立 的 点 在 移动 事件 中 出 现 的 次 序 是 不 国定 的 。 因 此 ， 从 一 个 事件 到 另 一 个 事件 ， 点 的 
索引 值 是 可 以 改变 的 ， 但 点 的 ID 在 它 的 生命 周期 内 是 保证 不 会 改变 的 。 使 用 getPointerld() 可 
以 获得 一 个 点 的 ID， 在 手势 随后 的 移动 事件 中 ， 就 可 以 用 该 ID 来 追踪 这 个 点 。 对 于 随后 一 系 


列 的 事件 ， 可 以 使 用 findPointerlndex() 有 函数 ， 来 获得 对 应 给 定 ID 的 点 在 移动 事件 中 的 索引 值 


o 


如 下 : 





private int mActivePointerId; 
public boolean onTouchEvent(MotionEvent event) { 


// Get the pointer ID 
mActivePointerId = event.getPointerId(0); 


// ... Many touch events later... 


// Use the pointer ID to find the index of the active pointer 
// and fetch its position 

int pointerIndex = event.findPointerIndex(mActivePointerId); 
// Get the pointer's current position 

float x = event.getX(pointerIndex); 

float y = event.getY(pointerIndex); 


获取 MotionEvent 的 动作 


我 们 应 该 总 是 使 用 getActionMasked() 函 数 〈 或 者 用 MotionEventCompat.getActionMasked() 
这 个 兼容 版 本 更 好 ) 来 获取 MotionEvent 的 动作 (action)。 与 四 的 getAction() 函 数 不 同 的 

是 ， getActionMasked() 是 设计 用 来 处 理 多 点 触摸 的 。 它 会 返回 执行 过 的 动作 的 掩 码 值 ， 不 包 
括 点 的 索引 位 。 然 后 ， 我 们 可 以 使 用 getactionIndex() 来 获得 与 该 动作 关联 的 点 的 索引 值 。 
这 在 接 下 来 的 代码 段 中 可 以 看 到 。 


Note: 这 个 样 例 使 用 的 是 MotionEventCompat 类 。 该 类 在 Support Library 中 。 我 们 应 该 
使 用 MotionEventCompat 类 ， 来 提供 对 更 多 平台 的 支持 。 需 要 注意 的 一 点 

是 ，MotionEventCompat 并 不 是 MotionEvent 类 的 蔡 代 品 。 准 确 来 说 ， 它 提供 了 一 些 静 态 
工具 类 函数 ， 我 们 可 以 把 MotionEvent 对 象 作为 参数 传递 给 这 些 函 数 ， 来 得 到 与 事件 相关 
的 动作 。 
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int action = 


MotionEventCompat.getActionMasked(event); 


// Get the index of the pointer associated with the action. 


int index - MotionEventCompat.getActionIndex(event); 


int xPos - -1; 


int yPos = -1; 


Log.d(DEBUG TAG,"The action is " + actionToString(action)); 


if (event.getPointerCount() > 1) { 
Log.d(DEBUG TAG, "Multitouch event"); 
// The coordinates of the current screen contact, relative to 


// the responding View or Activity. 


xPos 


yPos 


} else f 


// Single touch event 


(int)MotionEventCompat.getX(event, index); 
(int)MotionEventCompat.getY(event, index); 


Log.d(DEBUG TAG,"Single touch event"); 
xPos - (int)MotionEventCompat.getX(event, index); 


yPos - (int)MotionEventCompat.getY(event, index); 


// Given an action int, 


returns a string description 


public static String actionToString(int action) { 


switch (action) ( 


case 
case 
case 
case 
case 
case 
case 


} 


MotionEvent 
MotionEvent 
MotionEvent 
MotionEvent 
MotionEvent 
MotionEvent 
MotionEvent 


returni s 


.ACTION_DOWN: return "Down"; 
.ACTION_MOVE: return "Move"; 
.ACTION_POINTER_ 
.ACTION_UP: return "Up"; 

.ACTION_POINTER_UP: return "Pointer Up"; 
.ACTION_OUTSIDE: 
.ACTION_CANCEL : 


DOWN: return "Pointer Down"; 


return "Outside"; 
return "Cancel"; 


关于 多 点 触摸 的 更 多 内 容 以 及 示例 ， 可 以 查看 拖 搜 与 缩放 章节 。 


拖 搜 与 缩放 


编写 :Andrwyw - 原文 :http://developer.android.com/training/gestures/scale.html 


本 节 课 程 讲述 ， 使 用 onTouchEvent() 截 获 触摸 事件 后 ， 如 何 使 用 触摸 手势 拖 找 、 缩 放 屏 幕 上 
的 对 象 。 


HEAR — Pt HR 


如 果 我 们 的 目标 版 本 为 3.0 或 以 上 ， 我 们 可 以 使 用 View.OnDragListener 监 听 内 置 的 拖 放 
(drag-and-drop) 事件 ， 拖 搜 与 释放 中 有 更 多 相关 描述 。 


对 于 触摸 手势 来 说 ， 一 个 很 常见 的 操作 是 在 屏幕 上 拖 搜 一 个 对 象 。 接 下 来 的 代码 段 让 用 户 可 
以 拖 搜 屏幕 上 的 图 片 。 需 要 注意 以 下 几 点 : 


e 拖 搜 操作 时 ， 即 使 有 额外 的 手指 放置 到 屏幕 上 了 ，app 也 必须 保持 对 最 初 的 点 (手指 ) 的 
追踪 。 上 比如， 想象 在 拖 搜 图 片 时 ， 用 户 放置 了 第 二 根 手指 在 屏幕 上 ， 并 且 抬 起 了 第 一 根 
手指 。 如 果 我 们 的 app 只 是 单独 地 追踪 每 个 点 ， 它 会 把 第 二 个 点 当做 默认 的 点 ， 并 且 把 图 
片 移 到 该 点 的 位 置 。 

e 为 了 防止 这 种 情况 发 生 ， 我 们 的 app 需 要 区 分 初始 点 以 及 随后 任意 的 触摸 点 。 要 做 到 这 一 
点 ， 它 需要 追踪 处 理 多 触摸 手势 章节 中 提 到 过 的 ACTION POINTER DOWN 和 
ACTION POINTER UP 事件 。 每 当 第 二 根 手 指 按 下 或 拿 起 
时 ，ACTION_POINTER_DOWN 和 ACTION POINTER UP 事件 就 会 传递 
给 onTouchEvent() 回调 函数 。 

e 当 ACTION_POINTER_UP 事 件 发 生 时 ， 示 例 程 序 会 移 除 对 该 点 的 索引 值 的 引用 ， 确 保 操 
作 中 的 点 的 ID(the active pointer ID) 不 会 引用 已 经 不 在 触摸 屏 上 的 触摸 点 。 这 种 情况 下 ， 
app 会 选择 另 一 个 触摸 点 来 作为 操作 中 (active) 的 点 ， 并 保存 它 当 前 的 x、y 值 。 由 于 
在 ACTION_MOVE 事 件 时 ， 这 个 保存 的 位 置 会 被 用 来 计算 屏幕 上 的 对 象 将 要 移动 的 距 
离 ， 所 以 app 会 始终 根据 正确 的 触摸 点 来 计算 移动 的 距离 。 


下 面 的 代码 段 允 许 用 户 拖 搜 屏幕 上 的 对 象 。 它 会 记录 操作 中 的 点 (active pointer) 的 初始 位 
置 ， 计 算 触 摸 点 移动 过 的 距离 ， 再 把 对 象 移动 到 新 的 位 置 。 如 上 所 述 ， 它 也 正确 地 处 理 了 额 
外 触摸 点 的 可 能 。 


需要 注意 的 是 ， 代 码 段 中 使 用 了 getActionMasked() 有 函数 。 我 们 应 该 始终 使 用 这 个 函数 (或 者 
最 好 用 MotionEventCompat.getActionMasked() 这 个 兼容 版 本 ) ey DAMM 的 动 
ft (action) ° #4#18 Aj getAction() HA > getactionMasked() 就 是 设计 用 来 处 理 多 点 触摸 的 。 它 
会 返回 执行 过 的 动作 的 掩 码 值 ， 不 包括 该 点 的 索引 位 。 


// The 'active pointer' is the one currently moving our object. 


private int mAct 


@Override 

public boolean o 
// tet the S 
mScaleDetect 


final int ac 


switch (acti 
case MotionE 
final in 
final fl 
final fl 


// Remem 
mLastTou 
mLastTou 
// Save 
mActiveP 
break; 


case MotionE 
// Find 
final in 


finalni 
pagare uL nl 
/vCalcu 
faimai ti 


final fl 


mPosX += 
mPosY += 


invalida 
// Remem 
mLastTou 
mLastTou 
break; 
case MotionE 


mActiveP 
break; 


case MotionE 


ivePointerId - INVALID POINTER ID; 


nTouchEvent(MotionEvent ev) { 
caleGestureDetector inspect all events. 
or.onTouchEvent (ev); 


tion = MotionEventCompat.getActionMasked(ev); 


on) { 
vent.ACTION_DOWN: { 


t pointerIndex = MotionEventCompat.getActionIndex(ev); 
oat x = MotionEventCompat.getX(ev, pointerIndex); 
oat y = MotionEventCompat.getY(ev, pointerIndex); 


ber where we started (for dragging) 
chx xe 

chY = y; 

the ID of this pointer (for dragging) 


ointerId = MotionEventCompat.getPointerId(ev, 0); 


vent.ACTION MOVE: { 

the index of the active pointer and fetch its position 

t pointerIndex - 

MotionEventCompat.findPointerIndex(ev, mActivePointerId); 


oat x - MotionEventCompat.getX(ev, pointerIndex); 
oat y - MotionEventCompat.getY(ev, pointerIndex); 
late the distance moved 
oat dx - x - mLastTouchX; 
oat dy = y - mLastTouchY; 
dx; 
dy; 
te(); 
ber this touch position for the next move event 


ChX 
chy 


X; 


y; 


vent.ACTION UP: ( 
ointerId - INVALID POINTER ID; 


vent.ACTION CANCEL: ( 


mActivePointerId = INVALID POINTER ID; 
break; 


case MotionEvent.ACTION POINTER UP: { 


final int pointerIndex - MotionEventCompat.getActionIndex(ev); 
final int pointerId = MotionEventCompat.getPointerId(ev, pointerIndex); 


if (pointerId == mActivePointerId) { 
// This was our active pointer going up. Choose a new 
// active pointer and adjust accordingly. 
final int newPointerIndex = pointerIndex == 0 ? 1 : 0; 
mLastTouchX - MotionEventCompat.getX(ev, newPointerIndex); 
mLastTouchY - MotionEventCompat.getY(ev, newPointerIndex); 
mActivePointerId = MotionEventCompat.getPointerId(ev, newPointerIndex); 


j 


break; 


} 
} 


return true; 


过 拖 搜 平 移 


前 一 节 展 示 了 一 个 ， 在 屏幕 上 拖 捉 对 象 的 例子 。 另 一 个 常见 的 场景 是 平移 (panning) ， 平 移 
是 指 用 户 通 过 拖 搜 移动 引起 x、y 轴 方向 发 生 滚动 (scrolling)。 上 面 的 代码 段 直接 截获 了 
MotionEvent 动 作 来 实现 拖 找 。 这 一 部 分 的 代码 段 ， 利 用 了 平台 对 常用 手势 的 内 置 支持 。 它 重 
* J GestureDetector.SimpleOnGestureListener#onScroll() $ Z& ° 


更 详细 地 说 ， 当 用 户 拖 搜 手指 来 平移 内 容 时 ， onscroll() 函数 就 会 被 调用 。 onscroli() HA 
只 会 在 手指 按 下 的 情况 下 被 调用 ， 一 旦 手指 离开 屏幕 了 ， 要 么 手势 终止 ， 要 么 快速 滑动 (fling) 
手势 开始 (如 果 手 指 在 离开 屏幕 前 快速 移动 了 一 段 距离 ) 。 关 于 滚动 与 快速 滑动 的 更 多 讨 

论 ， 可 以 查看 滚动 手势 动画 章节 。 


这 里 是 onscroll() 的 相关 代码 段 : 


// The current viewport. This rectangle represents the currently visible 
// chart domain and range. 
private RectF mCurrentViewport - 

new RectF(AXIS X MIN, AXIS Y MIN, AXIS X MAX, AXIS Y MAX); 


// The current destination rectangle (in pixel coordinates) into which the 
// chart data should be drawn. 
private Rect mContentRect; 


private final GestureDetector.SimpleOnGestureListener mGestureListener 
= new GestureDetector.SimpleOnGestureListener() { 


@Override 
public boolean onScroll(MotionEvent e1, MotionEvent e2, 
float distanceX, float distanceY) { 
// Scrolling uses math based on the viewport (as opposed to math using pixels). 


// Pixel offset is the offset in screen pixels, while viewport offset is the 
// offset within the current viewport. 
float viewportOffsetX - distanceX * mCurrentViewport.width() 
/ mContentRect.width(); 
float viewportOffsetY - -distanceY * mCurrentViewport.height() 
/ mContentRect.height(); 


// Updates the viewport, refreshes the display. 
setViewportBottomLeft( 
mCurrentViewport.left + viewportOffsetx, 


mCurrentViewport.bottom + viewportOffsetY); 


mekurn thue, 


onscroll() 函数 中 滑动 视窗 (viewport) 来 响应 触摸 手势 的 实现 : 


Jee 
* Sets the current viewport (defined by mCurrentViewport) to the given 
* X and Y positions. Note that the Y value represents the topmost pixel position, 
* and thus the bottom of the mCurrentViewport rectangle. 
2 
private void setViewportBottomLeft(float x, float y) { 
/* 
* Constrains within the scroll range. The scroll range is simply the viewport 
* extremes (AXIS X MAX, etc.) minus the viewport size. For example, if the 
* extremes were 0 and 10, and the viewport size was 2, the scroll range would 
w oE O Eo eta 
2 


float curWidth = mCurrentViewport.width(); 

float curHeight - mCurrentViewport.height(); 

x = Math.max(AXIS X MIN, Math.min(x, AXIS X MAX - curWidth)); 
y = Math.max(AXIS Y MIN + curHeight, Math.min(y, AXIS Y MAX)); 


mCurrentViewport.set(x, y - curHeight, x + curWidth, y); 


// Invalidates the View to update the display. 
ViewCompat.postInvalidateOnAnimation(this); 


使 用 触摸 手势 进行 缩放 


如 同 检测 常用 手势 章节 中 提 到 的 ，GestureDetector 可 以 帮助 我 们 检测 Android 中 的 常见 手势 ， 
例如 滚动 ， 快 速 滚动 以 及 长 按 。 对 于 缩放 ，Android 也 提供 了 ScaleGestureDetector 类 。 当 我 
们 想 让 view 能 识别 额外 的 手势 时 ， 我 们 可 以 同时 使 用 GestureDetector 和 
ScaleGestureDetector 类 。 


为 了 报告 检测 到 的 手势 事件 ， 手 势 检 测 需要 一 个 作为 构造 函数 参数 的 listener 对 

象 。ScaleGestureDetector 使 用 ScaleGestureDetectorOnScaleGestureListener。Android 提 
供 了 ScaleGestureDetector.SimpleOnScaleGestureListener 类 作为 帮助 类 ， 如 果 我 们 不 是 关 
注 所 有 的 手势 事件 ， 我 们 可 以 继承 (extend) 它 。 


基本 的 缩放 示例 


下 面 的 代码 段 展 示 了 缩放 功能 中 的 基本 部 分 。 


private ScaleGestureDetector mScaleDetector; 
private float mScaleFactor - 1.f; 


public MyCustomView(Context mContext){ 
// View code goes here 


mScaleDetector - new ScaleGestureDetector(context, new ScaleListener()); 


@Override 

public boolean onTouchEvent(MotionEvent ev) { 
// Let the ScaleGestureDetector inspect all events. 
mScaleDetector .onTouchEvent (ev); 
return true, 


@Override 
public void onDraw(Canvas canvas) { 
super .onDraw(canvas); 


canvas.save(); 
canvas.scale(mScaleFactor, mScaleFactor); 


// onDraw() code goes here 


canvas.restore(); 


private class ScaleListener 
extends ScaleGestureDetector.SimpleOnScaleGestureListener { 
@Override 
public boolean onScale(ScaleGestureDetector detector) { 
mScaleFactor *= detector.getScaleFactor(); 


// Don't let the object get too small or too large. 
mScaleFactor = Math.max(0.if, Math.min(mScaleFactor, 5.0f)); 


invalidate(); 
return true; 


更 加 复杂 的 缩放 示例 


这 是 本 章节 提供 的 InteractiveChart 示例 中 三 个 更 复杂 的 示范 。 通过 使 
用 ScaleGestureDetector 中 的 "span"(getCurrentSpanX/Y) 和 "focus"(getFocusX/Y) 功 
能 ，Interactivechart 示例 同时 支持 滚动 (平移 ) 以 及 多 指 缩 放 。 


@Override 
private RectF mCurrentViewport = 
new RectF(AXIS_X_MIN, AXIS_Y_MIN, AXIS_X_MAX, AXIS_Y_MAX); 
private Rect mContentRect; 
private ScaleGestureDetector mScaleGestureDetector; 


public boolean onTouchEvent(MotionEvent event) { 
boolean retVal = mScaleGestureDetector.onTouchEvent (event); 


retVal = mGestureDetector.onTouchEvent(event) || retVal; 
return retVal || super.onTouchEvent(event); 
} 
PEE 
* The scale listener, used for handling multi-finger scale gestures. 
i 


private final ScaleGestureDetector.OnScaleGestureListener mScaleGestureListener 
= new ScaleGestureDetector.SimpleOnScaleGestureListener() ( 

/** 
* This is the active focal point in terms of the viewport. Could be a local 
* variable but kept here to minimize per-frame allocations. 
2 

private PointF viewportFocus - new PointF(); 

private float lastSpanX; 

private float lastSpany; 


// Detects that new pointers are going down. 
@Override 
public boolean onScaleBegin(ScaleGestureDetector scaleGestureDetector) { 
lastSpanX - ScaleGestureDetectorCompat. 
getCurrentSpanX(scaleGestureDetector); 
lastSpanY - ScaleGestureDetectorCompat. 
getCurrentSpanY(scaleGestureDetector); 
return Enue; 


@Override 
public boolean onScale(ScaleGestureDetector scaleGestureDetector) { 


float spanX = ScaleGestureDetectorCompat. 
getCurrentSpanX(scaleGestureDetector); 

float spanY - ScaleGestureDetectorCompat. 
getCurrentSpanY(scaleGestureDetector); 


float newwidth = lastSpanX / spanX * mCurrentViewport.width(); 
float newHeight - lastSpanY / spanY * mCurrentViewport.height(); 


float focusX - scaleGestureDetector.getFocusX(); 

float focusY - scaleGestureDetector.getFocusY(); 

// Makes sure that the chart point is within the chart region. 

// See the sample for the implementation of hitTest() 

hitTest(scaleGestureDetector.getFocusX(), 
scaleGestureDetector.getFocusY(), 


viewportFocus); 


mCurrentViewport.set( 
viewportFocus.x 
- newwidth * (focusX - mContentRect.left) 
/ mContentRect.width(), 
viewportFocus.y 
- newHeight * (mContentRect.bottom - focusY) 
/ mContentRect.height(), 
9, 
9); 
mCurrentViewport.right = mCurrentViewport.left + newWidth; 
mCurrentViewport.bottom = mCurrentViewport.top + newHeight; 


// Invalidates the View to update the display. 


ViewCompat .postInvalidateOnAnimation(InteractiveLineGraphView. this); 
lastSpanX = spanX; 


lastSpanY - spanY; 
return true; 


}; 


管理 ViewGroup 中 的 触摸 事件 


编写 :Andrwyw - 原文 :http://developer.android.com/training/gestures/viewgroup.html 


为 很 多 时 候 是 用 ViewGroup 的 子 类 来 做 不 同 触摸 事件 的 目标 ， 而 不 是 ViewGroup 本 身 ， 所 以 
处 理 ViewGroup 中 的 触摸 事件 需要 特别 注意 。 为 了 确保 每 个 view 能 正确 地 接收 到 它们 想 要 的 
触摸 事件 ， 可 以 重 写 onlnterceptTouchEvent() 函 数 。 


在 ViewGroup 中 截获 触摸 事件 


每 当 在 ViewGroup (包括 它 的 子 View) 的 表面 上 检测 到 一 个 触摸 事 

件 ，onlnterceptTouchEvent() 都 会 被 调用 。 如 果 onInterceptTouchEvent() 返 

€] true ，MotionEvent 就 被 截获 了 ， 这 表示 它 不 会 被 传递 给 其 子 View， 而 是 传递 给 该 父 view 
自身 的 onTouchEvent() 方 法 。 


onInterceptTouchEvent() 方法 让 父 view 能 够 在 它 的 子 view 之 前 处 理 触摸 事件 。 如 果 我 们 

让 onInterceptTouchEvent() 返回 true ， 则 之 前 处 理 触 摸 事 件 的 子 view 会 收 

到 ACTION CANCEL 事 件 ， 并且 该 点 之 后 的 事件 会 被 发 送 给 该 父 view 自 身 

的 onTouchEvent( ) BE 进行 常规 处 理 ° onInterceptTouchEvent() 也 可 以 返回 false ， 这 样 
事件 沿 view 层 级 分 发 到 目标 前 ， 父 View 可 以 简单 地 观察 该 事件 。 这 里 的 目标 是 指 ， 通 

过 onTouchEvent() 处 理 消息 事件 的 view ° 


接 下 来 的 代码 段 中 ， MyviewGroup 继承 自 ViewGroup。 MyviewGroup 有 多 个 子 view。 如 果 我 们 
在 某 个 子 View 上 水 平地 拖 动手 指 ， 该 子 view 不 会 接收 到 触摸 事件 ， 而 是 应 该 

由 MyViewGroup 处 理 这 些 触摸 事件 来 滚动 它 的 内 容 。 然 而 ， 如 果 我 们 点 击 子 view 中 的 button * 
或 重 直 地 滚动 子 view， 则 父 view 不 会 截获 这 些 触摸 事件 ， 因 为 子 view 本 身 就 是 预定 目标 。 在 
这 些 情况 下 ^ onInterceptTouchEvent( ) 应 该 返回 false ， MyViewGroup 的 onTouchEvent( ) 也 
不 会 被 调用 。 


public class MyViewGroup extends ViewGroup { 


private int mTouchSlop; 


ViewConfiguration vc - ViewConfiguration.get(view.getContext()); 
mTouchSlop - vc.getScaledTouchSlop(); 


@Override 
public boolean onInterceptTouchEvent(MotionEvent ev) { 


管理 ViewGroup 中 的 触摸 事件 


Jd 
* This method JUST determines whether we want to intercept the motion. 
* If we return true, onTouchEvent will be called and we do the actual 
* scrolling there. 
uy 


final int action = MotionEventCompat.getActionMasked(ev); 


// Always handle the case of the touch gesture being complete. 

if (action == MotionEvent.ACTION CANCEL || action == MotionEvent.ACTION UP) ( 
// Release the scroll. 
mIsScrolling = false; 
return false; // Do not intercept touch event, let the child handle it 


switch (action) ( 
case MotionEvent.ACTION_MOVE: { 
if (mIsScrolling) { 
// We're currently scrolling, so yes, intercept the 
// touch event! 
return true, 


// If the user has dragged her finger horizontally more than 
// the touch slop, start the scroll 


// left as an exercise for the reader 
final int xDiff = calculateDistanceX(ev); 


// Touch slop should be calculated using ViewConfiguration 
// constants. 
if (xDiff > mTouchSlop) { 

// Start scrolling! 

mIsScrolling - true; 

return true, 


j 


break; 


// In general, we don't want to intercept touch events. They should be 
// handled by the child view. 
return false; 


@Override 
public boolean onTouchEvent(MotionEvent ev) { 
// Here we actually handle the touch event (e.g. if the action is ACTION_MOVE, 
// scroll this container). 
// This method will only be called if the touch event was intercepted in 
// onInterceptTouchEvent 
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注意 ViewGroup 也 提供 了 requestDisallowlnterceptTouchEvent() 方 法 。 当 子 view 不 想 该 父 view 
和 祖先 view 通 过 onInterceptTouchEvent() 截获 它 的 触摸 事件 时 ， 可 调用 ViewGroup 的 该 方 
法 。 


使 用 ViewConfiguration 的 常量 


上 面 的 代码 段 中 使 用 了 当前 的 ViewConfiguration 来 初始 化 mTouchslop 变量 。 我 们 可 以 使 
用 ViewConfiguration 类 来 获取 Android 系 统 常 用 的 一 些 距 离 、 速 度 、 时 间 值 。 


"Touch slop” 是 指 在 被 识别 为 移动 的 手势 前 ， 用 户 触摸 可 移动 的 那 一 段 像素 距离 。Touch slop 
通常 用 来 预防 用 户 在 做 一 些 其 他 触摸 操作 时 ， 出 现 意 外 地 滑动 ， 例 如 触摸 屏幕 上 的 组 件 。 


另外 两 个 常用 的 ViewConfiguration 函数 是 getScaledMinimumFlingVelocity() 和 
getScaledMaximumFlingVelocity()。 这 两 个 函数 会 返回 初始 化 一 个 快速 滑动 (fling) 的 最 小 、 最 
KRR (TAE) ， 以 像素 每 秒 为 测量 单位 。 如 : 


ViewConfiguration vc = ViewConfiguration.get(view.getContext()); 
private int mSlop - vc.getScaledTouchSlop(); 

private int mMinFlingVelocity - vc.getScaledMinimumFlingVelocity(); 
private int mMaxFlingVelocity - vc.getScaledMaximumFlingVelocity(); 


case MotionEvent.ACTION MOVE: { 


float deltaX - motionEvent.getRawX() - mDownX; 
if (Math.abs(deltaX) > mSlop) { 
// A swipe occurred, do something 


} 


case MotionEvent.ACTION_UP: { 
} if (mMinFlingVelocity <= velocityX && velocityX <= mMaxFlingVelocity 


&& velocityY < velocityX) { 
// The criteria have been satisfied, do something 


扩展 子 view 的 可 触摸 区 域 


Android 提 供 了 TouchDelegate 类 ， 让 父 view 扩 展 超出 子 view 自 身边 界 的 可 触摸 区 域 。 这 在 当 
子 view 很 小 ， 但 需要 一 个 更 大 的 触摸 区 域 时 非常 有 用 。 如 果 需 要 ， 我 们 也 可 以 使 用 这 种 方式 
来 实现 对 子 view 的 触摸 区 域 的 收缩 。 


在 下 面 的 例子 中 ，ImageButton 对 象 是 所 谓 的 "delegate view" (是 指 触摸 区 域 将 被 父 view 扩 展 
的 那个 子 view) 。 这 是 布局 文件 : 


<RelativeLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android: id="@t+id/parent_layout" 
android: layout_width="match_parent" 
android: layout_height="match_parent" 
tools:context=".MainActivity" > 


<ImageButton android: id="@+id/button" 
android: layout_width="wrap_content" 
android: layout_height="wrap_content" 
android: background="@null" 
android:src="@drawable/icon" /> 
</RelativeLayout> 


下 面 的 代码 段 做 了 这 样 几 件 事 : 


+ 但 2^ 


e. 获得 父 view 对 象 并 发 送 一 个 Runnable 到 UI 线 程 。 这 会 确保 父 view 在 调用 getHitRect() 函 数 

前 会 布局 它 的 子 view。 getHitRect() 函数 会 获得 子 view 在 父 view 坐 标 系 中 的 点 击 矩 形 
(触摸 区 域 ) 。 

e 找到 ImageButton 子 view， 然 后 调用 getHitRect() 来 获得 它 的 触摸 区 域 的 边界 。 

e d /&ImageButtonf4 & 4E 7E 84 ib Je o 

e &f5|15—^-TouchDelegatext & > ied Rit 6) s d 4E 76 Fe |mageButton Fview/t A 4 X 
传递 给 它 。 

e 设置 父 view 的 TouchDelegate， 这 样 在 touch delegate 边 界 内 的 点 击 就 会 传递 到 该 子 view 
de 


在 ImageButton 子 view 的 touch delegate 范 围 内 ， 父 view 会 接收 到 所 有 的 触摸 事件 。 如 果 触 摸 
事件 发 生 在 子 view 自 身 的 点 击 矩 形 中 ， 父 view 会 把 触摸 事件 交 给 子 view 处 理 。 


public class MainActivity extends Activity { 


QOverride 

protected void onCreate(Bundle savedInstanceState) ( 
super.onCreate(savedInstanceState); 
setContentView(R.layout.activity main); 
// Get the parent view 
View parentView - findViewById(R.id.parent layout); 


parentView.post(new Runnable() { 
// Post in the parent's message queue to make sure the parent 
// lays out its children before you call getHitRect() 





up F 835 


@Override 
public void run() { 
// The bounds for the delegate view (an ImageButton 
// in this example) 
Rect delegateArea = new Rect(); 
ImageButton myButton = (ImageButton) findViewById(R.id.button); 
myButton.setEnabled(true); 
myButton.setOnClickListener(new View.OnClickListener() { 
@Override 
public void onClick(View view) { 
Toast.makeText(MainActivity.this, 
"Touch occurred within ImageButton touch region.", 
Toast.LENGTH SHORT).show(); 


3); 


// The hit rectangle for the ImageButton 
myButton.getHitRect(delegateArea); 


// Extend the touch area of the ImageButton beyond its bounds 
// on the right and bottom. 
delegateArea.right += 100; 
delegateArea.bottom += 100; 


// Instantiate a TouchDelegate. 

// "delegateArea" is the bounds in local coordinates of 

// the containing view to be mapped to the delegate view. 

// "myButton" is the child view that should receive motion 

// events. 

TouchDelegate touchDelegate - new TouchDelegate(delegateArea, 
myButton); 


// Sets the TouchDelegate on the parent view, such that touches 
// within the touch delegate bounds are routed to the child. 
if (View.class.isInstance(myButton.getParent())) { 

((View) myButton.getParent()).setTouchDelegate(touchDelegate); 


3); 
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ah SE ABE LE HT A 


编写 :zhaochunqi - /$ X<:http://developer.android.com/training/keyboard-input/index.html 


当当 前 焦点 在 UI 的 文本 框 上 时 ，Android 系统 会 在 屏幕 上 显示 一 个 键盘 一 被 称 为 软 输入 法 。 
为 了 提供 最 好 的 用 户 体验 ， 我 们 可 以 指定 我 们 期 望 的 输入 类 型 的 特征 (例如 ， 是 否 是 电话 号 
码 或 Email 地 址 ) 和 输入 法 的 表现 形式 (例如 ， 是 否 需 要 自动 纠正 拼写 错误 ) 。 


除了 使 用 屏幕 上 的 输入 法 ，Android 也 支持 实体 键盘 ， 所 以 充分 利用 可 能 会 被 用 户 接 入 的 外 接 
键盘 来 优化 用 户 的 交互 体验 是 很 重要 的 。 


接 下 来 的 课程 会 讨论 上 述 这 些 主题 和 更 多 相关 内 容 。 


Lessons 


指定 输入 法 类 型 


学 习 如 何 表现 特定 的 软 输 入 法 ， 如 为 电话 号 码 、 网 址 和 其 他 一 些 格式 所 做 的 设计 。 同 样 应 该 
学 习 如 何 指定 一 些 属 性 ， 例 如 拼写 建议 和 像 确定 (Done) 或 者 下 一 步 (Next) 这 样 的 动作 按钮 。 


处 理 输入 法 的 显示 


学 习 如 何 合适 地 展示 软 输入 法 ， 和 如 何 让 我 们 的 布局 作出 调整 ， 来 适合 因为 输入 法 而 减少 的 
屏幕 空间 。 


支持 键盘 导航 
学 习 如 何 验证 用 户 是 否 能 够 使 用 键盘 导航 我 们 的 应 用 以 及 如 何 对 导航 顺序 做 出 必要 的 改变 。 
处 理 键盘 行为 


学 习 如 何 对 用 户 的 键盘 输入 作出 回应 。 


B X 输入 法 类 型 


编写 :zhaochunqi - /® X<:http://developer.android.com/training/keyboard-input/style.htm| 
型 的 文本 输入 ， 如 Email 地 址 ， 电 话 号 码 ， 或 者 纯 文 本 。 为 应 用 中 的 
p. 


每 个 文本 框 都 对 应 特定 类 
入 类 型 是 很 重要 的 ， 这 样 做 可 以 让 系统 展示 更 为 合适 的 软 输入 法 (比如 


每 一 个 文本 框 指定 输 
虚拟 键盘 ) 。 


除了 输入 法 可 用 的 按钮 类 型 之 外 ， 我 们 还 应 该 指定 一 些 行为 ， 例 如 ， 输 入 法 是 否 提供 拼写 建 
议 ， 新 的 句子 首 字母 大 写 ， 和 将 回 车 按钮 蔡 换 成 动作 按钮 (如 Done 或 者 Next). 。 这 节 课 介 
绍 了 如 何 添加 这 些 属性 。 


be a 3E 
Ht Fe RA 
过 将 android:inputType 属性 添加 到 «EditText» 节点 中 ， 我 们 可 以 为 文本 框 声明 输入 法 。 


通 
举例 来 说 ， 如 果 我 们 想 要 一 个 用 于 输入 电话 号 码 的 输入 法 ， 那 么 使 用 "phone" dà: 


«EditText 
android: id="@+id/phone" 
android: layout_width="fill_parent" 
android:layout height-"wrap content" 
android:hint-"Qstring/phone hint" 
android:inputType-"phone" /> 


2 ABC 3 DEF 


4 GHI 5 JKL 6 MNO 


7 PARS 8TUV * wxYz 


* # 0 + 





Figure 1. phone 输入 类 型 


或 者 如 果 文 本 框 用 于 输入 密码 > 那么 使 用 "textPassword" 值 来 隐藏 用 户 的 输入 : 


«EditText 
android: id="@+id/password" 
android: hint="@string/password_hint" 
android: inputType="textPassword" 
/> 
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Figure 2. textPassword 输入 类 型 


有 几 种 可 供 选择 的 值 在 android:inputrype 记录 在 属性 中 ， 一 些 值 可 以 组 合 起 来 实现 特定 的 
输入 法 外 观 和 附加 的 行为 。 


> Ly 、、 ae ae 
开启 拼写 建议 和 其 它 行为 
android:inputType 属性 允许 我 们 为 输入 法 指定 不 同 的 行为 。 最 为 重要 的 是 ， 如 果 文 本 框 用 于 
基本 的 文本 输入 (如 短信 息 ) ， 那 么 我 们 应 该 使 用 "textautocorrect" 值 来 开启 自动 拼写 修 
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Figure 3. 添加 textAutoCorrect 为 拼写 错误 提供 自动 修正 


我 们 可 以 将 不 同 的 行为 和 输入 法 形式 组 合 到 android:inputType 这 个 属性 。 如 : 如 何 创建 一 个 
文本 框 ， 里 面 的 句子 首 字母 大 写 并 开启 拼写 修正 : 


«EditText 
android: id="@+id/message" 
android: layout_width="wrap_content" 
android: layout_height="wrap_content" 
android: inputType= 
"textCapSentences | textAutoCorrect" 
/> 


指定 输入 法 的 行为 


多 数 的 软 键盘 会 在 底部 角落 里 为 用 户 提供 一 个 合适 的 动作 按钮 来 触发 当前 文本 框 的 操作 。 默 
认 情 况 下 ， 系 统 使 用 Next 或 者 Done， 除 非 我 们 的 文本 框 允许 多 行文 本 

(如 android:inputType="textMultiLine" ) ， 这 种 情况 下 ， 动 作 按钮 就 是 回 车 换行 。 然 而 ， 我 
们 可 以 指定 一 些 更 适合 我 们 文本 框 的 额外 动作 ， 比 如 Send 和 Go。 


ar NU . Send 


Figure 4. 3 441 AY android:imeoptions-"actionsend" ， 会 出 现 Send 按钮 。 


使 用 android:imeOptions 属性 ， 并 设置 一 个 动作 值 (如 "actionsend" 或 
"actionsearch" ) ， 来 指定 键盘 的 动作 按钮 。 如 : 


<EditText 
android:id="@+id/search" 
android:layout_width="fill_parent" 
android:layout_height="wrap_content" 
android:hint="@string/search_hint" 
android:inputType="text" 
android:imeOptions-"actionSend" /> 


然后 ， 我 们 可 以 通过 为 EditText 节点 定义 TextView.OnEditorActionListener 来 监听 动作 按钮 
的 按压 。 在 监听 器 中 ， 响 应 Editorlnfo 类 中 定义 的 适合 的 IME action ID > 4 
IME_ACTION_SEND 。 例 如 : 


EditText editText = (EditText) findViewById(R.id.search); 
editText.setOnEditorActionListener(new OnEditorActionListener() ( 
@Override 
public boolean onEditorAction(TextView v, int actionId, KeyEvent event) { 
boolean handled = false; 
if (actionId == EditorInfo.IME_ACTION_SEND) { 
sendMessage(); 
handled = true; 
} 


return handled; 


3); 


处 理 输 入 法 可 见 性 


^h 5 :zhaochungi - 原文 :http://developer.android.com/training/keyboard- 
input/visibility.html 


当 输 入 焦点 移入 或 移出 可 编辑 的 文本 框 时 ，Android 会 相应 的 显示 或 隐藏 输入 法 (如 虚拟 键 
盘 ) 。 系 统 也 会 决定 输入 法 上 方 的 UI 和 文本 框 的 显示 方式 。 举 例 来 说 ， deis 间 被 
压缩 时 ， 文 本 框 可 能 填充 输入 法 上 方 所 有 的 空间 。 对 于 多 数 的 应 用 来 说 ， 这些 上 默认 的 行为 基 
本 就 足够 了 。 


然而 ， 在 一 些 事例 中 ， 我 们 可 能 会 想 要 更 加 直接 地 控制 输入 法 的 显示 ， 指 定 在 输入 法 显示 的 
时 候 ， 如 何 显示 我 们 的 布局 。 这 节 课 会 解释 如 何 控制 和 响应 输入 法 的 可 见 性 


在 Activity 司 动 时 显示 输入 法 


尽管 Android 会 在 Activity 启 动 时 将 焦点 放 在 布局 中 的 第 一 个 文本 框 ， 但 是 并 不 会 显示 输入 法 。 
因为 输入 文本 可 能 并 不 是 activity 中 的 首要 任务 ， 所 以 不 显示 输入 法 是 很 合理 的 。 可 是 ， 如 果 
输入 文本 确实 是 首要 的 任务 (如 在 登录 界面 中 ) ， 那 么 可 能 需要 默认 显示 输入 法 。 

为 了 在 activity 局 动 时 显示 输入 法 ， 添 加 android:windowSoftlnputMode 属性 到 «activity» 节点 
中 ， 并 将 该 属性 的 值 设 为 "statevisible" 。 如 下 : 


«application ... » 
«activity 
android:windowSoftInputMode-"stateVisible" ... > 


«/activity» 


</application> 


Note: 如 果 用 户 的 设备 有 一 个 实体 键盘 ， 那 么 不 会 显示 软 输入 法 。 


根据 需要 显示 输入 法 
如 果 我 们 想 要 确保 输入 法 在 activity 生 命 周期 的 某 个 方法 中 是 可 见 的 ， 那 么 可 以 使 用 


InputMethodManager 来 实现 。 


举例 来 说 ， 下 面 的 方法 调用 了 一 个 需要 用 户 填写 文本 的 View， 调 用 了 requestFocus() 来 获取 
焦点 ， 然 后 调用 showSoftlnput() 来 打开 输入 法 。 


public void showSoftKeyboard(View view) { 
if (view.requestFocus()) { 
InputMethodManager imm = (InputMethodManager ) 
getSystemService(Context.INPUT METHOD SERVICE); 
imm.showSoftInput(view, InputMethodManager.SHOW IMPLICIT); 


Note: 一 旦 输入 法 可 见 ， 我 们 不 应 该 以 编程 的 方式 来 隐藏 它 。 系 统 会 在 用 户 结束 文本 框 
的 任务 时 隐藏 输入 法 ， 或 者 可 以 使 用 系统 控制 (如 返回 键 ) 来 隐藏 


o 


指定 UI 的 响应 方式 


当 输 入 法 显示 在 屏幕 上 时 ， 会 减少 app Ul 中 的 可 用 空间 。 系 统 会 决定 如 何 调整 Ul 可 见 的 部 
分 ， 但 是 这 样 做 不 一 定 正 确 。 为 了 确保 应 用 的 最 佳 表现 ， 我 们 应 该 在 UI 的 剩余 空间 中 展示 我 
们 想 要 展示 的 系统 界面 。 


为 了 在 activity 中 声明 合适 的 处 理 方 法 ， 可 以 在 manifest 文件 的 <activity> 节点 中 使 用 
android:windowSoftlnputMode 属性 ， 并 将 该 属性 的 值 设 为 "adjust"。 


举例 来 说 ， 为 了 确保 系统 会 在 可 用 空 
以 被 使 用 (尽管 可 能 需要 滑动 ) 一 一 使 用 "adjustResize" : 





«application ... » 
«activity 
android:windowSoftInputMode-"adjustResize" ... > 


«/activity» 


</application> 


我 们 可 以 结合 上 述 调整 说 明和 初始 化 输入 法 可 见 性 说 明 : 


<activity 


android:windowSoftInputMode-"stateVisible|adjustResize" ... > 
«/activity» 
如 果 UI 中 包含 用 户 可 能 需要 在 文本 输入 时 立即 执行 的 事情 么 使 用 "adjustResize" 是 很 


重要 的 。 例 如 ， 如 果 我 们 使 用 相对 布局 (relative layout) Dr ME ， 用 
"adjustResize" 来 重新 调整 大 小 ， 使 得 按钮 栏 出 现在 输入 法 上 方 。 


处 理 输入 法 可 见 性 


961 


支持 键盘 导航 


编写 :zhaochunqi - /$ x-:http;//developer.android.com/training/keyboard- 
input/navigation.html 


除了 软 键盘 输入 法 〈 如 虚拟 键盘 ) 以 外 ，Android 支 持 将 物理 键盘 连接 到 设备 上 。 键 盘 不 仅 方 
便 输 入 文本 ， 而 且 提 供 一 种 方法 来 导航 和 与 应 用 交互 。 尽 管 多 数 的 手持 设备 (如 手机 ) 使 用 

触摸 作为 主要 的 交互 方式 ， 但 是 随 着 平板 和 一 些 类 似 的 设备 正在 逐步 流行 起 来 ， 许 多 用 户 开 

始 喜 欢 外 接 键 盘 。 


随 着 更 多 的 Android 设 备 提供 这 种 体验 ， 优 化 应 用 以 支持 通过 键盘 与 应 用 进行 交互 变 得 越 来 越 
重要 。 这 节 课 介绍 了 怎样 为 键盘 导航 提供 更 好 的 支持 。 


Note: 对 那些 没有 使 用 可 见 导 航 提 示 的 应 用 来 说 ， 在 应 用 中 支持 方向 性 的 导航 对 于 应 用 
的 可 用 性 也 是 很 重要 的 。 在 我 们 的 应 用 中 完全 支持 方向 导航 还 可 以 帮助 我 们 使 用 诸如 
uiautomator 等 工具 进行 自动 化 用 户 界面 测试 。 


测试 应 用 
因为 Android 系 统 默认 开启 了 大 多 必要 的 行为 ， 所 以 用 户 可 能 已 经 可 以 在 我 们 的 应 用 中 使 用 键 
EST 


所 有 由 Android framework (如 Button 和 EditText) 提供 的 交互 部 件 是 可 获得 焦点 的 。 这 意味 着 
用 户 可 以 使 用 如 D-pad 或 键盘 等 控制 设备 ， 并 且 当 某 个 部 件 被 选中 时 ， 部 件 会 发 光 或 者 改变 外 
Xo 


为 了 测试 我 们 的 应 用 : 
1. 将 应 用 安装 到 一 个 带 有 实体 键盘 的 设备 上 。 


如 果 我 们 没有 带 实体 键盘 的 设备 ， 连 接 一 个 蓝牙 键盘 或 者 USB 键 盘 (尽管 并 不 是 所 有 的 设 
备 都 支持 USB 连 接 ) 


我 们 还 可 以 使 用 Android 模 拟 器 : 
i 在 AVD 管 理 器 中 ， 要 么 点 击 New Device， 要 么 选择 一 个 已 存在 的 文档 点 击 Clone » 
ii. 在 出 现 的 窗口 中 ， 确 保 Keyboard 和 D-pad 开启 。 


2. 为 了 验证 我 们 的 应 用 ， 只 是 用 Tab 键 来 进行 UI 导航， 确保 每 一 个 UI 控制 的 焦点 与 预期 的 一 
致 。 


找到 任何 不 在 预期 焦点 的 实例 。 


3. 从 头 开始 ， 使 用 方向 键 (键盘 上 的 箭头 键 ) 来 控制 应 用 的 寻 航 。 
在 UI 中 每 一 个 被 选中 的 元 素 上 ， 按 上 、 下 、 左 、 右 。 
找到 每 个 不 在 预期 焦点 的 实例 。 


如 果 我 们 找到 任何 使 用 Tab 键 或 方向 键 后 导航 的 效果 不 如 预期 的 实例 ， 那 么 在 布局 中 指定 焦点 
应 该 聚焦 在 哪里 ， 如 下 面 几 部 分 所 讨论 的 。 


处 理 Tab 和 导航 


当 用 户 使 用 键盘 上 的 Tab 键 导航 我 们 的 应 用 时 ， 系 统 会 根据 组 件 在 布局 中 的 显示 顺序 ， 在 组 件 
之 间 传 递 焦点 。 如 果 我 们 使 用 相对 布局 (relative layout) ， 例 如 ， 在 屏幕 上 的 组 件 顺 序 与 布 
局 文件 中 组 件 的 顺序 不 一 致 ， 那 么 我 们 可 能 需要 手动 指定 焦点 顺序 。 


举例 来 说 ， 在 下 面 的 布局 文件 中 ， 两 个 对 齐 右边 的 按钮 和 一 个 对 齐 第 二 个 按钮 左边 的 文本 
框 。 为 了 把 焦点 从 第 一 个 按钮 传递 到 文本 框 ， 然 后 再 传递 到 第 二 个 按钮 ， 布 局 文件 需要 使 用 
属性 android:nextFocusForward， 清 楚 地 为 每 一 个 可 被 选中 的 组 件 定义 焦点 顺序 : 


«RelativeLayout ...> 
«Button 
android: id="@+id/buttoni" 
android: layout_alignParentTop="true" 
android: layout_alignParentRight="true" 
android: nextFocusForward="@+id/editTexti" 
Qoo He 
<Button 
android:id="@+id/button2" 
android: layout_below="@id/button1i" 
android: nextFocusForward="@+id/button1i" 
io LES 
«EditText 
android:id="@id/editText1i" 
android: layout_alignBottom="@+id/button2" 
android: layout_toLeftOf="@id/button2" 
android: nextFocusForward="@+id/button2" 
/> 
</RelativeLayout> 


现在 焦点 从 button1 到 button2 再 到 editrexti ， 改 成 了 按照 在 屏幕 上 出 现 的 顺序 : 


buttoni 到 


editText1 再 到 button2 。 


处 理 方向 导航 


用 户 也 能 够 使 用 键盘 上 的 方向 键 在 我 们 的 app 中 寻 航 (这 种 行为 与 在 D-pad 和 轨迹 球 中 的 导航 一 
臻 )。 系 统 提 供 了 一 个 最 佳 猜测 : 根据 屏幕 上 view 的 布局 ， 在 给 定 的 方向 上 ， 应 该 将 交 掉 放 在 
哪个 view 上 。 然 而 有 时 ， 系 统 会 猜测 错误 。 


当 在 给 定 的 方向 进行 导航 时 ， 如 果 系 统 没 有 传递 焦点 给 合适 的 View， 那 么 指定 接收 焦点 的 
view 来 使 用 如 下 的 属性 : 


e android:nextFocusUp 
e android:nextFocusDown 
e android:nextFocusL eft 
e android:nextFocusRight 


当 用 户 导 航 到 那个 方向 时 ， 每 一 个 属性 指定 了 下 一 个 接收 焦点 的 view， 如 根据 view ID 来 指 
定 。 举 例 来 说 : 


<Button 
android: id="@+id/button1i" 
android: nextFocusRight="@t+tid/button2" 
android: nextFocusDown="@+id/editTexti" 
人 

<Button 
android:id-"Qid/button2" 
android:nextFocusLeft-"Qid/buttoni" 
android:nextFocusDown-"(Qid/editText1" 
mm dE 

«EditText 
android: id="@id/editText1" 
android: nextFocusUp="@id/button1i" 

i> 


处 理 按键 动作 


编写 :zhaochunqi - 原文 :http://developer.android.com/training/keyboard- 
input/commands.html 


当 用 户 选中 一 个 可 编辑 的 文本 view (如 EditText 组 件 ) ， 而 且 用 户 连接 了 一 个 实体 键盘 时 ， 
所 有 输入 由 系统 处 理 。 然 而 ， 如 果 我 们 想 接管 或 直接 处 理 键 瘟 输入 ， 那 么 可 以 通过 实现 
KeyEvent.Callback 接口 的 回调 方法 ， 如 onKeyDown() 和 onKeyMultiple() 来 完成 上 述 目 的 。 


为 Activity 和 View 类 都 实现 了 KeyEvent.Callback 接口 ， 所 以 通常 我 们 应 该 在 这 些 类 的 继 
承 中 重 写 回调 方法 。 


Note: 当 使 用 KeyEvent 类 和 相关 的 API 处 理 键盘 事件 时 ， 我 们 应 该 期 望 这 种 键盘 事件 
只 从 实体 键盘 发 出 。 我 们 永远 不 应 该 依赖 从 一 个 软 输入 法 〈 如 屏幕 键盘 ) 来 接收 按键 事 
件 。 


处 理 单个 按键 事件 


处 理 单个 的 按键 点 击 ， 需 要 适当 地 实现 onKeyDown() 或 onKeyUp()。 通 常 ， 我 们 使 用 
onKeyUp() 来 确保 我 们 只 接收 一 个 事件 。 如 果 用 户 点 击 并 按 住 按钮 不 放 ，onKeyDown() 会 被 
调用 多 次 。 


举例 ， 这 个 实现 响应 一 些 键盘 按键 来 控制 游戏 : 


@Override 
public boolean onKeyUp(int keyCode, KeyEvent event) { 
switch (keyCode) { 
case KeyEvent.KEYCODE D: 
moveShip(MOVE LEFT); 
return true; 
case KeyEvent.KEYCODE F: 
moveShip(MOVE RIGHT); 
retunn true; 
case KeyEvent .KEYCODE_J: 
fireMachineGun(); 
return true; 
case KeyEvent .KEYCODE_K: 
fireMissile(); 
return tnue; 
default: 
return super.onKeyUp(keyCode, event); 


处 理 修 饰 键 


为 了 对 修饰 键 (例如 将 一 个 按键 与 Shift 或 者 Control 键 组 合 ) 进行 回应 ， 我 们 可 以 查询 
KeyEvent 来 传递 到 回调 方法 。 一 些 方法 ， 如 getModifiers() 和 getMetaState()， 提 供 一 些 关 
于 修饰 键 的 信息 。 然 而 ， 最 简单 的 解决 方案 是 用 像 isShiftPressed() 和 isCtriPressed() 等 方 
法 ， 检 查 我 们 关心 的 修饰 键 是 否 正在 被 按 下 。 


例如 ， 有 一 个 onKeyDown() 的 实现 ， 当 Shift 键 和 一 个 其 他 按键 按 下 时 ， 做 一 些 额外 的 处 理 : 


@Override 
public boolean onKeyUp(int keyCode, KeyEvent event) { 
switch (keyCode) { 


case KeyEvent.KEYCODE J: 
if (event.isShiftPressed()) { 
fireLaser(); 
} else { 
fireMachineGun(); 
j 
Eeeurnmeauey 
case KeyEvent.KEYCODE K: 
if (event.isShiftPressed()) 1 
fireSeekingMissle(); 
} else { 
fireMissile(); 
j 
return tenue; 
default: 
return super.onKeyUp(keyCode, event); 


we ab Ip Be 
支持 游戏 控制 器 
编写 :heray1990 - 原文 :http://developer.android.com/training/game- 
controllers/index.html 


我 们 可 以 通过 支持 游戏 控制 器 来 增强 用 户 体验 。Android framework 提供 了 APIs 来 检测 和 处 
理 游戏 控制 器 的 用 户 输入 。 


这 节 课 介绍 了 如 何 使 我 们 的 游戏 在 不 同 的 Android API levels(API level 9 或 者 更 高 ) 问 稳定 地 
工作 。 还 介绍 了 如 何 通过 在 我 们 的 App 中 支持 多 个 游戏 控制 器 来 增强 用 户 体验 。 


Lessons 


处 理 控制 器 输入 动作 


学 习 如 何 处 理 游 戏 控制 器 常用 的 输入 元 素 ， 包 括 方向 键 按钮 (D-pad) 、 游 戏 键盘 和 扬 
杆 。 


在 不 同 的 Android 系统 版 本 支持 控制 器 
学 习 如 何 使 游戏 控制 器 在 运行 不 同 Android 系统 版 本 的 设备 上 保持 行为 一 致 。 
支持 多 个 游戏 控制 器 


学 习 如 何 检测 和 使 用 多 个 同时 连接 的 游戏 控制 器 。 


处 理 控制 蜂 输 入 动作 


编写 :heray1990 - 原文 :http://developer.android.com/training/game-controllers/controller- 
input.html 


在 系统 层面 上 ，Android 会 以 Android 按键 码 值 和 坐标 值 的 形式 来 报告 来 自 游戏 控制 器 的 输入 
didi 在 我 们 的 游戏 应 用 里 ， 我 们 可 以 接收 这 些 码 值 和 坐标 值 ， 并 将 它们 转化 成 特定 的 游戏 
行为 o 


eur id 制 器 通过 有 线 连接 或 者 无 线 配 对 到 Android 设备 时 ， 系 统 会 自动 检测 控 
制 器 ， 将 它 设置 成 输入 设备 并 且 开 始 报告 它 的 输入 事件 。 我 们 的 游戏 应 用 可 以 通过 在 活动 的 
Activity 或 者 被 选中 的 View 里 调用 下 面 这 些 回调 方法 ， 来 接收 上 述 输入 事件 〈 要 么 在 
Activity > $2 Æ View 中 实现 实现 这 些 回 调 方法 ， 不 要 两 个 地 方 都 实现 回调 ) e 


e 在 Activity 中 : 
o dispatchGenericMotionEvent(android.view.MotionEvent) 
m 处 理 一 般 的 运动 事件 ， 如 摇动 摇 杆 
o dispatchKeyEvent(android.view.KeyEvent) 
m 处 理 按键 事件 ， 如 按 下 或 者 释放 游戏 键盘 的 按键 或 者 D-pad 按钮 。 
e 在 View 中 : 
o onGenericMotionEvent(android.view.MotionEvent) 
m 处 理 一 般 的 运动 事件 ， 如 摇动 摇 杆 
o onKeyDown(int, android.view.KeyEvent) 
m 处 理 按 下 一 个 按键 的 事件 ， 如 按 下 游戏 键盘 的 按键 或 者 D-pad 按钮 。 
o onKeyUp(int, android.view.KeyEvent) 
m 处 理 释放 一 个 按键 的 事件 ， 如 释放 游戏 键盘 的 按键 或 者 D-pad 按钮 。 


建议 的 方法 是 从 与 用 户 交互 的 View 对 象 捕获 事件 。 请 查看 下 面 回 调 函数 的 对 象 ， 来 获取 关于 
接收 到 输入 事件 的 类 型 : 


KeyEvent : 描述 方向 按键 (D-pad) 和 游戏 按键 事件 的 对 象 。 按 键 事件 伴随 着 一 个 表示 特定 
按键 触发 的 按键 码 值 (key code)， 如 DPAD DOWN 或 者 BUTTON _A。 我 们 可 以 通过 调用 
getKeyCode() 或 者 从 按键 事件 回调 方法 (如 onKeyDown()) 来 获得 按键 码 值 。 


MotionEvent : 描述 摇 杆 和 肩 键 运动 的 输入 。 动 作 事件 伴随 着 一 个 动作 码 (action code) 和 一 
系列 坐标 值 (axis values) 。 动 作 码 表示 出 现 变化 的 状态 ， 例 如 摇动 一 个 摇 杆 。 坐 标 值 描述 
了 特定 物理 操控 的 位 置 和 其 它 运 例如 AXIS. X 或 者 AXIS_RTRIGGER。 我 们 可 以 通 
过 调用 getAction() 来 获得 动作 码 ， 通 过 调用 getAxisValue() 来 获得 坐标 值 。 


View 回调 方法 与 处 理 KeyEvent 和 MotionEvent 对 象 ， 
来 处 理 常 用 控制 器 (游戏 键盘 按键 、 方 向 按键 和 摇 杆 ) 的 输入 。 


«a name="input=></a> 


验 十 游戏 控制 器 是 否 已 连接 


在 报告 输入 事件 的 时 候 ，Android 不 会 区 分 游戏 控制 器 事件 与 非 游戏 控制 器 事件 。 例 如 ， 一 个 
E E le Oe ee ee ee 
则 表示 摇 杆 水 平移 动 的 位 置 。 如 果 我 们 的 游戏 关注 游戏 控制 器 的 输入 ， 那 么 我 们 应 该 首先 检 
测 相应 的 事件 来 源 类 型 。 


通过 调用 getSources() 来 获 pde de a cH Dd ， 来 判断 一 个 已 连接 的 输入 设 
备 是 不 是 一 个 游戏 控制 器 。 我 们 可 以 通过 测试 以 查看 下 面 的 字段 是 否 被 设置 : 


se 
虽然 一 般 的 游戏 手柄 都 会 有 方向 控制 键 ， 但 是 这 个 源 类 型 并 不 代表 游戏 控制 器 具有 D- 
pad 按钮 。 

e SOURCE DEAD A ped cs Mur s 

e SOURCE JOYSTICK 源 类 型 表示 输入 设备 有 膛 控 杆 (如 ， 会 通过 AXIS X 和 AXIS Y 
记录 动作 的 扬 杆 ) 。 


下 面 的 一 小 段 代码 介绍 了 一 个 helper 方法 ， 它 的 作用 是 让 我 们 检验 已 接 入 的 输入 设备 是 否 是 
游戏 控制 器 。 如 果 检 测 到 是 游戏 控制 器 ， 那 么 这 个 方法 会 获得 游戏 控制 器 的 设备 ID。 然后 ， 

我 们 应 该 将 每 个 设备 ID 与 游戏 中 的 玩家 关联 起 来 ， 并 且 单 独处 理 每 个 已 接 入 的 玩家 的 游戏 操 
作 。 想 更 详细 地 了 解 关 于 在 一 台 Android 设 备 中 同时 支持 多 个 游戏 控制 器 的 方法 ， 请 见 支持 多 
个 游戏 控制 器 。 


public ArrayList getGameControllerIds() { 
ArrayList gameControllerDeviceIds - new ArrayList(); 
int[] deviceIds = InputDevice.getDeviceIds(); 
for (int deviceId : deviceIds) { 
InputDevice dev - InputDevice.getDevice(deviceId); 
int sources - dev.getSources(); 


// Verify that the device has gamepad buttons, control sticks, or both. 
if (((sources & InputDevice.SOURCE GAMEPAD) -- InputDevice.SOURCE GAMEPAD) 
|| ((sources & InputDevice.SOURCE JOYSTICK) 
== InputDevice.SOURCE JOYSTICK)) { 
// This device is a game controller. Store its device ID. 
if (!gameControllerDeviceIds.contains(deviceld)) { 
gameControllerDeviceIds.add(deviceId); 
j 
} 
} 


return gameControllerDeviceIds; 


另外 ， 我 们 可 能 想 去 检查 已 接 入 的 单个 游戏 控制 器 的 输入 性 能 。 这 种 检查 在 某 些 场合 会 很 有 
用 ， 例 如 ， 我 们 希望 游戏 只 用 到 兼容 的 物理 操控 。 


用 下 面 这 些 方法 检测 一 个 游戏 控制 器 是 否 支持 一 个 特定 的 按键 码 或 者 坐标 码 : 


e 在 Android 4.4 (API level 19). 或 者 更 高 的 系统 中 ， 调 用 haskeys(int) 来 确定 游戏 控制 器 
是 否 支持 某 个 按键 码 。 

e 在 Android 3.1 (API level 12) 或 者 更 高 的 系统 中 ， 首 先 调 用 getMotionRanges()， 然 后 
在 每 个 返回 的 InputDevice.MotionRange 对 象 中 调用 getAxis() 来 获得 坐标 ID。 这 样 就 可 
以 得 到 游戏 控制 器 支持 的 所 有 可 用 坐标 轴 。 


WE ` n> 
处 理 游戏 手柄 按键 
Figure 1 介绍 了 Android 如 何 将 按键 码 和 坐标 值 映 射 到 实际 的 游戏 手柄 上 。 


Front View Top View 





Figure 1. 一 个 常用 的 游戏 手柄 的 外 形 


上 图 的 标注 对 应 下 面 的 内 容 : 

1. AXIS. HAT. X, AXIS. HAT. Y, DPAD UP, DPAD DOWN, DPAD LEFT, DPAD RIGHT 
2. AXIS. X, AXIS. Y, BUTTON. THUMBL 

3. AXIS. Z, AXIS RZ, BUTTON. THUMBR 

4. BUTTON X 

5. BUTTON A 

6. BUTTON Y 

7. BUTTON B 

8. BUTTON R1 

9. AXIS RTRIGGER, AXIS THROTTLE 


一 
eo 


. AXIS. LTRIGGER, AXIS BRAKE 
. BUTTON L1 


= 
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游戏 手柄 产生 的 通用 的 按键 码 包 括 BUTTON A ` BUTTON B ` BUTTON SELECT 和 
BUTTON_START。 当 按 下 D-pad 中 间 的 交 又 按键 时 ， 一 些 游戏 控制 器 会 触发 

DPAD CENTER 按键 码 。 我 们 的 游戏 可 以 通过 调用 getKeyCode() 或 者 从 按键 事件 回调 (如 
onKeyDown()) 得 到 按键 码 。 如 果 一 个 事件 与 我 们 的 游戏 相关 ， 那 么 将 其 处 理 成 一 个 游戏 动 
作 。Table 1 列 出 供 大 多 数 通用 游戏 手柄 按钮 使 用 的 推荐 游戏 动作 。 


Table 1. 供 游戏 手柄 使 用 的 推荐 游戏 动作 


游戏 动作 按键 码 

B DS Ü E? m» 
Gone E 中 启动 游戏 ， 或 者 在 游戏 过 程 中 暂停 / 取 BUTTON START 
显示 菜单 BUTTON_SELECT 和 


KEYCODE MENU 

跟 Android 导 航 设计 指导 中 的 Back 导 航行 为 一 样 KEYCODE BACK 

返回 到 菜单 中 上 一 项 BUTTON B 

确认 选择 ， 或 者 执行 主要 的 游戏 动作 BUTTON A 和 DPAD CENTER 


* 我 们 的 游戏 不 应 该 依赖 于 Start、Select 或 者 Menu 按 键 的 存在 。 


Tip: 可 以 考虑 在 游戏 中 提供 一 个 配置 界面 ， 使 得 用 户 可 以 个 性 化 游戏 控制 器 与 游戏 动作 
的 映射 


下 面 的 代码 介绍 了 如 何 重 写 onKeyDown() 来 将 BUTTON A 和 DPAD CENTER 按钮 结合 到 
一 个 游戏 动作 。 


public class GameView extends View { 


@Override 


public boolean onKeyDown(int keyCode, KeyEvent event) { 
boolean handled = false; 


if ((event.getSource() & InputDevice .SOURCE_GAMEPAD ) 
== InputDevice.SOURCE_GAMEPAD) { 
if (event.getRepeatCount() == 0) { 
switch (keyCode) { 


// Handle gamepad and D-pad button presses to 
// navigate the ship 


default: 


if (isFireKey(keyCode)) { 


// Update the ship object to fire lasers 
handled = true; 


break; 


if (handled) { 


retunn Erue; 


} 


return super.onKeyDown(keyCode, event); 
} 


private static boolean isFireKey(int keyCode) { 


// Here we treat Button A and DPAD CENTER as the primary action 
// keys for the game. 


return keyCode == KeyEvent.KEYCODE DPAD CENTER 


|| keyCode -- KeyEvent.KEYCODE BUTTON A; 
} 


Note: 在 Android 4.2 (API level 17) 和 更 低 版 本 的 系统 中 ， 系 统 默 认 会 把 BUTTON A 
当 作 Android Back (返回 ) 键 。 如 果 我 们 的 应 用 支持 这 些 Android 版 本 ， 请 确保 将 


BUTTON A 转换 成 主要 的 游戏 动作 。 引 用 Build. VERSION.SDK INT 值 来 决定 设备 上 当 
前 的 Android SDK 版 本 。 


处 理 D-pad 输入 
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四 方向 的 方向 键 (D-pad) 在 很 多 游戏 控制 器 中 是 一 种 很 常见 的 物理 控制 。Android 将 D-pad 
的 上 和 下 按键 按压 报告 成 AXIS HAT Y 事件 (范围 从 -1.0 (+) 到 1.0 CF) ) ， 将 D-pad 的 
左 或 者 右 按键 按压 报告 成 人 AXIS_HAT_X 事件 (范围 从 -1.0 CE) 到 1.0 ( 右 ) ) © 


一 些 游戏 控制 器 会 将 D-pad 按压 报告 成 一 个 按键 码 。 如 果 我 们 的 游戏 有 检测 D-pad 的 按压 ， 
那么 我 们 应 该 将 坐标 值 事 件 和 D-pad 按键 码 当 成 一 样 的 输入 事件 ， 如 table 2 介绍 的 一 样 。 


Table 2. D-pad 按键 码 和 坐标 值 的 推荐 默认 游戏 动作 。 


游戏 动作 D-pad 按键 码 坐标 值 

向 上 KEYCODE DPAD UP AXIS HAT. Y (从 0 到 -1.0) 
向 下 KEYCODE DPAD DOWN AXIS HAT. Y (从 0 到 1.0) 
向 左 KEYCODE DPAD LEFT AXIS HAT. X (从 0 到 -1.0) 
向 右 KEYCODE DPAD RIGHT AXIS. HAT. X. (从 0 到 1.0) 


下 面 的 代码 介绍 了 通过 一 个 helper 类 ， 来 检查 从 一 个 输入 事件 来 决定 D-pad 方向 的 坐标 值 和 
按键 码 。 


public class Dpad ( 
final static int UP - 
final static int LEFT = 
final static int RIGHT = 
final static int DOWN 
final static int CENTER 


WN EHR o 


int directionPressed = -1; // initialized to -1 


public int getDirectionPressed(InputEvent event) { 
if (!isDpadDevice(event)) { 
return -1; 


} 


// If the input event is a MotionEvent, check its hat axis values. 
if (event instanceof MotionEvent) { 


// Use the hat axis value to find the D-pad direction 
MotionEvent motionEvent = (MotionEvent) event; 

float xaxis - motionEvent.getAxisValue(MotionEvent.AXIS HAT X); 
float yaxis - motionEvent.getAxisValue(MotionEvent.AXIS HAT Y); 


// Check if the AXIS HAT X value is -1 or 1, and set the D-pad 
// LEFT and RIGHT direction accordingly. 
if (Float.compare(xaxis, -1.0f) == 0) { 
directionPressed = Dpad.LEFT; 
) eise if (Float.compare(xaxis, 1.0f) == 0) ( 
directionPressed = Dpad.RIGHT; 


} 
// Check if the AXIS_HAT_Y value is -1 or 1, and set the D-pad 


// UP and DOWN direction accordingly. 

else if (Float.compare(yaxis, -1.0f) == 0) ( 
directionPressed = Dpad.UP; 

} else if (Float.compare(yaxis, 1.0f) == 0) { 
directionPressed = Dpad.DOWN; 


// If the input event is a KeyEvent, check its key code. 
else if (event instanceof KeyEvent) { 


// Use the key code to find the D-pad direction. 

KeyEvent keyEvent = (KeyEvent) event; 

if (keyEvent.getKeyCode() == KeyEvent.KEYCODE DPAD LEFT) { 
directionPressed - Dpad.LEFT; 

} eise if (keyEvent.getKeyCode() == KeyEvent.KEYCODE DPAD RIGHT) { 
directionPressed - Dpad.RIGHT; 

} eise if (keyEvent.getKeyCode() -- KeyEvent.KEYCODE DPAD UP) ( 
directionPressed - Dpad.UP; 

} eise if (keyEvent.getKeyCode() == KeyEvent.KEYCODE DPAD DOWN) ( 
directionPressed - Dpad.DOWN; 

} eise if (keyEvent.getKeyCode() == KeyEvent.KEYCODE DPAD CENTER) { 
directionPressed - Dpad.CENTER; 


} 


return directionPressed; 


public static boolean isDpadDevice(InputEvent event) { 
// Check that input comes from a device with directional pads. 
if ((event.getSource() & InputDevice.SOURCE DPAD) 
!- InputDevice.SOURCE DPAD) { 
return true; 
else { 
return false; 


我 们 可 以 在 任意 想 要 处 理 D-pad 输入 (例如 ， 在 onGenericMotionEvent() 或 者 
onKeyDown() 回调 函数 ) 的 地 方 使 用 这 个 helper 类 。 


例如 : 


Dpad mDpad = new Dpad(); 


QOverride 
public boolean onGenericMotionEvent(MotionEvent event) { 


// Check if this event if from a D-pad and process accordingly. 
if (Dpad.isDpadDevice(event)) 1 


int press - mDpad.getDirectionPressed(event); 
switch (press) { 
case LEFT: 
// Do something for LEFT direction press 


return true; 
case RIGHT: 
// Do something for RIGHT direction press 


return true; 
case UP: 
// Do something for UP direction press 


return true; 


} 


// Check if this event is from a joystick movement and process accordingly. 


处 理 摇 杆 动作 


当 玩 家 移动 游戏 控制 器 上 的 摇 杆 时 ，Android 会 报告 一 个 包含 ACTION MOVE 动作 码 和 更 新 
摇 杆 在 坐标 轴 的 位 置 的 MotionEvent。 我 们 的 游戏 可 以 使 用 MotionEvent 提供 的 数据 来 确定 
是 否 发 生 据 杆 的 动作 。 


注意 到 摇 杆 移动 会 在 单个 对 象 中 批 处 理 多 个 移动 示例 。MotionEvent 对 象 包 含 每 个 扬 杆 坐标 当 
前 的 位 置 和 每 个 坐标 轴 上 的 多 个 历史 位 置 。 当 用 ACTION MOVE 动作 码 (例如 摇 杆 移动 ) 来 
报告 移动 事件 时 ，Android 会 高 效 地 批 处 理 坐 标 值 。 由 坐标 值 组 成 的 不 同 的 历史 值 比 当前 的 坐 
标 值 要 旧 ， 比 之 前 报告 的 任意 移动 事件 要 新 。 详 情 见 MotionEvent 参考 文档 。 


我 们 可 以 使 用 历史 信息 ， 根 据 扬 杆 输 入 更 精确 地 表达 游戏 对 象 的 活动 。 调 用 getAxisValue() 
或 者 getHistoricalAxisValue() 来 获取 现在 和 历史 的 值 。 我 们 也 可 以 通过 调用 getHistorySize() 
来 找到 摇 杆 事件 的 历史 点 号 码 。 


下 面 的 代码 介绍 了 如 何 重 写 onGenericMotionEvent() 回调 函数 来 处 理 摇 杆 输入 。 我 们 应 该 首 
先 处 理 历史 坐标 值 ， 然 后 处 理 当 前 值 。 


public class GameView extends View { 


@Override 
public boolean onGenericMotionEvent(MotionEvent event) { 


// Check that the event came from a game controller 

if ((event.getSource() & InputDevice.SOURCE_JOYSTICK) == 
InputDevice.SOURCE_JOYSTICK && 
event.getAction() == MotionEvent.ACTION MOVE) ( 


// Process all historical movement samples in the batch 
final int historySize - event.getHistorySize(); 


// Process the movements starting from the 

// earliest historical position in the batch 

for (int i = 0; i « historySize; i++) { 
// Process the event at historical position i 
processJoystickInput(event, i); 


// Process the current movement sample in the batch (position -1) 
processJoystickInput(event, -1); 
return true; 


} 


return super.onGenericMotionEvent(event); 


在 使 用 摇 杆 输入 之 前 ， 我 们 需要 确定 扬 杆 是 否 居中 ， 然 后 计算 相应 的 坐标 移动 距离 。 一 般 扬 
杆 会 有 一 个 平面 区 ， 即 在 坐标 (0, 0) 附近 一 个 值 范围 内 的 坐标 点 都 被 当 作 是 中 点 。 如 果 
Android 系统 报告 坐标 值 掉 落 在 平面 区 内 ， 那 么 我 们 应 该 认为 控制 器 处 于 静止 (FRE X y 
两 个 坐标 轴 都 是 静止 的 ) 。 


下 面 的 代码 介绍 了 一 个 用 于 计算 沿 着 每 个 坐标 轴 的 移动 距离 的 helper 方法 。 我 们 将 在 后 面 讨 
论 的 processJoystickInput() 方法 中 调用 这 个 helper 方法 。 





private static float getCenteredAxis(MotionEvent event, 
InputDevice device, int axis, int historyPos) { 
final InputDevice.MotionRange range = 
device.getMotionRange(axis, event.getSource()); 


// A joystick at rest does not always report an absolute position of 
// (0,0). Use the getFlat() method to determine the range of values 
// bounding the joystick axis center. 
if (range !- null) { 
final float flat - range.getFlat(); 
final float value = 
historyPos « 0 ? event.getAxisValue(axis): 
event.getHistoricalAxisValue(axis, historyPos); 


// Ignore axis values that are within the 'flat' region of the 
// joystick axis center. 


if (Math.abs(value) > flat) { 
return value; 
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将 它们 都 放 在 一 起 ， 下 面 是 我 们 如 何在 游戏 中 处 理 摇 杆 移动 : 


private void processJoystickInput(MotionEvent event, 
int historyPos) { 


InputDevice mInputDevice - event.getDevice(); 


// Calculate the horizontal distance to move by 

// using the input value from one of these physical controls: 

// the left control stick, hat axis, or the right control stick. 

float x = getCenteredAxis(event, mInputDevice, 
MotionEvent.AXIS X, historyPos); 

if (x == 0) ( 


X - getCenteredAxis(event, mInputDevice, 
MotionEvent.AXIS HAT X, historyPos); 
} 
if (x == 0) ( 
x = getCenteredAxis(event, mInputDevice, 
MotionEvent.AXIS Z, historyPos); 
} 


// Calculate the vertical distance to move by 
// using the input value from one of these physical controls: 
// the left control stick, hat switch, or the right control stick. 
float y = getCenteredAxis(event, mInputDevice, 
MotionEvent.AXIS Y, historyPos); 


inay 0 


y = getCenteredAxis(event, mInputDevice, 
MotionEvent.AXIS_HAT_Y, historyPos); 
} 
i O c0) 6 
y = getCenteredAxis(event, mInputDevice, 
MotionEvent.AXIS RZ, historyPos); 
} 


// Update the ship object based on the new x and y values 


为 了 支持 除了 单个 扬 杆 之 外 更 多 复杂 的 功能 ， 按 照 下 面 的 做 法 : 


e 处 理 两 个 控制 器 摇 杆 。 很 多 游戏 控制 器 左右 两 边 都 有 摇 杆 。 对 于 左 扬 杆 ，Android 会 报告 
水 平方 向 的 移动 为 AXIS_X 事件 ， 重 直方 向 的 移动 为 AXIS_Y 事件 。 对 于 右 摇 杆 ， 
Android 会 报告 水 平方 向 的 移动 为 AXIS_Z 事件 ,垂直 方向 的 移动 为 AXIS_RZ 事件 。 确 
保 在 代码 中 处 理 两 个 摇 杆 。 


e 处 理 肩 键 按压 (但 需要 提供 另 一 种 输入 方法 ) 。 一 些 控制 器 会 有 左右 肩 键 。 如 果 存 在 这 
些 按键 ， 那 么 Android 报告 左肩 键 按压 为 一 个 AXIS_LTRIGGER 事件 ， 右 肩 键 按压 为 一 
个 AXIS_RTRIGGER 事件 。 在 Android 4.3 (API level 18) 中 ， 一 个 产生 了 
AXIS_LTRIGGER 事件 的 控制 器 也 会 报告 一 个 完全 一 样 的 AXIS. BRAKE 坐标 值 。 同 


样 ，AXIS_RTRIGGER 对 应 AXIS_GAS ° Android 会 报告 模拟 按键 按压 为 从 0.0 (4 
放 ) 911.0 (GET) 的 标准 值 。 并 不 是 所 有 的 控制 器 都 有 肩 键 ， 所 以 需要 允许 玩家 用 其 它 
按钮 来 执行 那些 游戏 动作 。 


在 不 同 的 Android 系统 版 本 支持 控制 器 


编写 :heray1990 - Æ X :http://developer.android.com/training/game- 
controllers/compatibility.html 


如 果 我 们 正 为 游戏 提供 游戏 控制 器 的 支持 ， 那 么 我 们 需要 确保 我 们 的 游戏 对 于 运行 着 不 同 
Android 版 本 的 设备 对 控制 器 都 有 一 致 的 响应 。 这 会 使 得 我 们 的 游戏 扩大 用 户 群 体 ， 同 时 ， 我 
们 的 玩家 可 YA 享受 即 使 他 们 切换 或 者 升级 Android 设备 的 时 候 ， ， 都 可 以 使 用 他 们 的 控制 器 无 
颖 对 接 的 游戏 体验 。 


这 节 课 展示 了 如 何 用 向 下 兼容 的 方式 使 用 Android 4.1 或 者 更 高 版 本 中 可 用 的 API， 使 我 们 的 
游戏 运行 在 Android 2.3 或 者 更 高 的 设备 上 时 ， 支 持 下 面 的 功能 


。 游戏 可 以 检测 是 否 有 一 个 新 的 游戏 控制 器 接 入 、 变 更 或 者 移 除 。 
。 游戏 可 以 查询 游戏 控制 器 的 兼容 性 。 
。 游戏 可 以 识别 从 游戏 控制 器 传 入 的 动作 事件 。 


这 节 课 的 例子 是 基于 controllersample.zip 提供 的 参考 实现 。 这 个 示例 介绍 了 如 何 实现 
InputManagerCompat 接口 来 支持 不 同 的 Android 版 本 。 我 们 必须 使 用 Android 4.1 (API level 
16) 或 者 更 高 的 版 本 来 编译 这 个 示例 代码 。 一 旦 编译 完成 ， 生 成 的 示例 app 可 以 在 任何 运行 
着 Android 2.3 (API level 9) 或 者 更 高 版 本 的 设备 上 运行 。 


准备 支持 游戏 控制 器 的 抽象 API 


假设 我 们 想 确定 在 运行 着 Android 2.3 (APllevel 9) 的 设备 上 ， 游 戏 控制 器 的 连接 状态 是 否 
发 生 改 变 。 无 论 如 何 ，API 只 在 Android 4.1 (API level 16) 或 者 更 高 的 版 本 上 可 用 ， 所 以 我 
们 需要 提供 一 个 支持 Android 4.1 (API level 16) 或 者 更 高 版 本 的 实现 方法 的 同时 ， 提 供 一 个 
支持 从 Android 2.3 到 Android 4.0 的 回 退 机 制 。 


为 了 帮助 我 们 确定 哪个 功能 需要 这 样 的 回 退 机 制 ，table 1 列 出 了 Android 2.3 (API level 
9) 、3.1 (API level 12) 和 4.1 (API level 16) 之 间 ， 对 于 支持 游戏 控制 器 的 不 同 之 处 。 


Table 1. API 在 不 同 Android 版 本 间 对 游戏 控制 器 支持 的 不 同 点 


Controller 
Information 


Device 
Identification 


Connection 


Status 


Input Event 
Identification 


Controller API level 


getinputDevicelds() 
getInputDevice() 
getVibrator() 
SOURCE_JOYSTICK 
SOURCE_GAMEPAD 
onInputDeviceAdded() 
oninputDeviceChanged() 
oninputDeviceRemoved() 


D-pad press ( KEYCODE DPAD UP, 
KEYCODE DPAD DOWN, 

KEYCODE DPAD LEFT, y 
KEYCODE DPAD RIGHT, 
KEYCODE DPAD CENTER) 


Gamepad button press ( BUTTON A, 
BUTTON B, BUTTON THUNBL, 
BUTTON THUMBR, BUTTON SELECT, 
BUTTON START, BUTTON R1, 

BUTTON L1, BUTTON R2, BUTTON L2) 


Joystick and hat switch movement ( AXIS X, 
AXIS. Y, AXIS Z, AXIS RZ, AXIS HAT X, 
AXIS HAT Y) 


Analog trigger press ( AXIS LTRIGGER, 
AXIS. RTRIGGER) 


API 
level 
12 


level 


我 们 可 以 使 用 抽象 化 概念 来 建立 能 够 工作 在 不 同 平台 的 版 本 识别 的 游戏 控制 器 支持 。 这 种 方 
法 包括 下 面 几 个 步骤 : 


1. 定义 一 个 中 间 Java 接口 来 抽象 化 我 们 游戏 需要 的 游戏 控制 器 功能 的 实现 。 


2. 创建 一 个 使 用 Android 4.1 和 更 高 版 本 API 的 接口 的 代理 实现 。 


3. 创建 一 个 使 用 Android 2.3 到 Android 4.0 之 间 可 用 的 API 的 接口 的 自 定义 实现 。 


4. 创建 在 运行 时 ， 在 这 上 述 这 些 实现 之 间 切 换 的 逻辑 ， 并 且 开 始 使 用 我 们 游戏 中 的 接口 。 


有 关 如 何 使 用 抽象 化 概念 来 保证 应 用 可 以 在 不 同 版 本 的 Android 之 间 ， 以 向 后 兼容 的 方式 工 
作 的 概述 ， 请 见 创建 向 后 兼容 的 Ul 。 


添加 向 后 兼容 的 接口 


Iranin zx 
garoid As 
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对 于 向 后 兼容 ， 我 们 可 以 创建 一 个 自 定 义 接口 ， 然 后 添加 特定 版 本 的 实现 。 这 种 方法 的 一 个 
优点 是 它 可 以 让 我 们 借鉴 Android 4.1 (API level 16) 上 支持 游戏 控制 器 的 公共 接口 。 


// The InputManagerCompat interface is a reference example. 
// The full code is provided in the ControllerSample.zip sample. 
public interface InputManagerCompat { 


public InputDevice getInputDevice(int id); 
public int[] getInputDevicelds(); 


public void registerInputDeviceListener( 
InputManagerCompat.InputDeviceListener listener, 
Handler handler); 

public void unregisterInputDeviceListener ( 
InputManagerCompat.InputDeviceListener listener); 


public void onGenericMotionEvent(MotionEvent event); 


public void onPause(); 
public void onResume(); 


public interface InputDeviceListener { 
void onInputDeviceAdded(int deviceId); 
void onInputDeviceChanged(int deviceId); 
void onInputDeviceRemoved(int deviceId); 


InputManagerCompat 接口 提供 了 下 面 的 方法 : 
getInputDevice() 

借鉴 getlnputDevice()。 包 括 代 表 一 个 游戏 控制 器 兼容 性 的 InputDevice xf & » 
getInputDeviceIds() 


借鉴 getlnputDevicelds()。 返 回 一 个 整 型 数组 ， 每 一 个 数组 成 员 表 示 一 个 不 同 输入 设备 的 
ID。 这 对 于 想 要 构建 一 个 支持 多 玩家 和 检测 连接 了 多 少 个 控制 器 的 游戏 是 很 有 用 的 。 


registerInputDeviceListener() 


借鉴 registerInputDeviceListener()。 注 册 一 个 监听 器 ， 当 一 个 新 的 设备 添加 、 改 变 或 者 移 除 的 
时 候 ， 我 们 会 收 到 通知 。 
unregisterIinputDeviceListener() 


a 


借鉴 unregisterlnputDeviceListener()。 注 销 一 个 输入 设备 监听 器 。 


onGenericMotionEvent() 


982 


借鉴 onGenericMotionEvent()。 让 我 们 的 游戏 截取 和 处 理 MotionEvent 对 象 和 代表 类 似 移动 
摇 杆 和 按 下 模拟 触发 器 等 事件 的 坐标 值 。 


onPause( ) 


当主 activity 暂停 或 者 当 游 戏 不 再 聚焦 时 ， 停 止 轮 询 游戏 控制 器 事件 。 


onResume( ) 


当主 activity 恢复 或 者 当 游戏 开始 和 在 前 台 运 行 时 ， 启 动 轮 询 游 戏 控制 器 事件 。 


InputDeviceListener 


借鉴 InputManagerInputDeviceListener 接口 。 当 添加 、 改 变 或 者 移 除 游戏 控制 器 时 ， 会 通知 
我 们 的 游戏 。 


下 一 步 ， 创 建 Inputmanagercompat 的 实现 ， 使 得 可 以 在 不 同 平台 版 本 间 工 作 。 如 果 我 们 的 游 
戏 运 行 在 Android 4.1 或 者 更 高 版 本 ， 调 用 InputManagercompat 方法 ， 代 理 实 现 调用 在 
InputManager 中 等 效 的 方法 。 然 而 ， 如 果 我 们 的 游戏 运行 在 Andoird 2.3 到 Android 4.0 > 4 

定义 的 实现 过 程 通过 使 用 不 晚 于 Android 2.3 引进 的 API 来 调用 InputManagerCompat 方法 。 
不 管 在 运行 时 使 用 哪 种 特定 版 本 的 实现 ， 实 现 会 透明 地 将 回调 结果 传 给 游戏 。 


"Proxy" implementation 
on Android 4.1 and higher 


— 


Your game code Interface 








Implementation on Android 
2.3 up to Android 4.0 


Figure 1. 接口 和 特定 版 本 实现 的 类 图 。 


实现 Android 4.1 和 更 高 版 本 的 接口 


InputManagerCompatVi6 是 InputManagerCompat 接口 的 实现 ， 该 接口 代理 方法 调用 一 个 
InputManager 和 InputManager.InputDeviceListener ° InputManagerz M £ 4% Context 得 
到 o 


// The InputManagerCompatV16 class is a reference implementation. 
// The full code is provided in the ControllerSample.zip sample. 
public class InputManagerV16 implements InputManagerCompat { 


private final InputManager mInputManager; 
private final Map mListeners; 


public InputManagerVi6(Context context) 1 
mInputManager - (InputManager) 
context.getSystemService(Context.INPUT SERVICE); 
mListeners - new HashMap(); 


@Override 
public InputDevice getInputDevice(int id) { 
return mInputManager.getInputDevice(id); 


@Override 
public int[] getInputDeviceIds() { 
return mInputManager.getInputDeviceIds(); 


static class Vi6éInputDeviceListener implements 
InputManager.InputDeviceListener { 
final InputManagerCompat.InputDeviceListener mIDL; 


public Vi6InputDeviceListener(InputDeviceListener idl) { 
mIDL = idl; 


@Override 
public void onInputDeviceAdded(int deviceId) { 
mIDL.onInputDeviceAdded(deviceId); 


// Do the same for device change and removal 


@Override 
public void registerInputDeviceListener(InputDeviceListener listener, 
Handler handler) { 
Vié6InputDeviceListener vi6Listener = new 
Vié6InputDeviceListener(listener) ; 
mInputManager.registerInputDeviceListener(vi6Listener, handler); 
mListeners.put(listener, vi6Listener); 


// Do the same for unregistering an input device listener 


QOverride 
public void onGenericMotionEvent(MotionEvent event) { 
// unused in V16 


@Override 
public void onPause() { 
// unused in V16 


@Override 
public void onResume() { 
// unused in V16 


实现 Android 2.3 到 Android 4.0 的 接口 


InputManagervo 实现 使 用 了 不 晚 于 Android 2.3 引进 的 APl。 为 了 创建 一 个 支持 Android 2.3 
到 Android 4.0 的  rnputManagercompat 实现 ， 我 们 可 以 使 用 下 面 的 对 象 : 


e 设备 ID 的 sparseArray 跟踪 已 连接 到 设备 的 游戏 控制 器 。 

e 一 个 Handler 来 处 理 设备 事件 。 当 一 个 app 启动 或 者 恢复 时 ， Handler 接收 一 个 消息 
来 开始 轮 询 游戏 控制 器 的 断 开 。 Handler 将 启动 一 个 循环 来 检查 每 个 已 知 连接 的 游戏 控 
制 器 并 且 查 看 是 否 返 回 一 个 设备 ID。 返 回 null 表示 游戏 控制 器 断 开 。 当 app 暂停 
时 ， Handler 停止 轮 询 。 

e 一 个 InputManagerCompat.InputDevicelistener 的 Map 对 象 。 我 们 会 使 用 这 个 listener 
来 更 新 跟踪 游戏 过 控 器 的 连接 状态 。 


// The InputManagerCompatV9 class is a reference implementation. 
// The full code is provided in the ControllerSample.zip sample. 
public class InputManagerV9 implements InputManagerCompat { 

private final SparseArray mDevices; 

private final Map mListeners; 

private final Handler mDefaultHandler; 


public InputManagerV9() { 
mDevices - new SparseArray(); 
mListeners - new HashMap(); 
mDefaultHandler - new PollingMessageHandler(this); 


实现 继承 Handler 的 PollingMessageHandler ， 并 重 写 handleMessage() 方法 。 这 个 方法 检 
ES 


连接 的 游戏 控制 器 是 否 已 经 断 开 并 且 通 知已 注册 的 listener » 


private static class PollingMessageHandler extends Handler { 
private final WeakReference mInputManager; 


PollingMessageHandler(InputManagerV9 im) { 
mInputManager = new WeakReference(im); 


@Override 
public void handleMessage(Message msg) { 
super .handleMessage(msg) ; 
switch (msg.what) { 
case MESSAGE TEST FOR DISCONNECT: 
InputManagerV9 imv - mInputManager.get(); 
if (null != imv) { 
long time - SystemClock.elapsedRealtime(); 
int size - imv.mDevices.size(); 
for (int i = 0; i < size; it+) { 
long[] lastContact = imv.mDevices.valueAt(i); 
if (null != lastContact) { 
if (time - lastContact[0] > CHECK_ELAPSED_TIME) { 
// check to see if the devaice has been 
// disconnected 
int id = imv.mDevices.keyAt(i); 
if (null == InputDevice.getDevice(id)) { 
// Notify the registered listeners 
// that the game controller is disconnected 


imv.mDevices.remove(id); 


} else f 
lastContact[0] = time; 


} 
sendEmptyMessageDelayed(MESSAGE_TEST_FOR_DISCONNECT, 


CHECK_ELAPSED_TIME); 


break; 


至 于 启动 和 停止 轮 询 游戏 控制 器 的 断 开 ， 重 写 这 些 方法 : 


private static final int MESSAGE TEST FOR DISCONNECT = 101; 
private static final long CHECK ELAPSED TIME = 3000L; 


@Override 
public void onPause() { 
mDefaultHandler.removeMessages(MESSAGE TEST FOR DISCONNECT); 


@Override 
public void onResume() { 
mDefaultHandler.sendEmptyMessageDelayed(MESSAGE TEST FOR DISCONNECT, 
CHECK ELAPSED TIME); 


重 写 onGenericMotionEvent() 方法 检测 输 入 设备 是 否 已 添加 。 当 系 统 通 知 一 个 动作 事件 时 
检查 这 个 事件 是 否 从 已 经 跟踪 过 的 还 是 新 的 设备 |D 中 发 出 。 如 果 是 新 的 设备 ID， 通 知已 注册 
的 listener ° 


@Override 
public void onGenericMotionEvent(MotionEvent event) { 
// detect new devices 
int id = event.getDeviceId(); 
long[] timeArray = mDevices.get(id); 
if (null == timeArray) { 
// Notify the registered listeners that a game controller is added 


timeArray = new long[1]; 
mDevices.put(id, timeArray); 


} 
long time = SystemClock.elapsedRealtime(); 


timeArray[0] = time; 


listener 的 通知 通过 使 用 Handler 对 象 发 送 一 个 DeviceEvent Runnable 对 象 到 消息 队列 来 
实现 。 DeviceEvent 包含 了 一 个 InputManagerCompat . InputDeviceListener 的 引用 。 当 
DeviceEvent 运行 时 ， 适 当 的 listener 回调 方法 会 被 调用 ， 标 志 游 戏 控 制 器 是 否 被 添加 、 改 变 
或 者 移 除 。 


@Override 
public void registerInputDeviceListener(InputDeviceListener listener, 
Handler handler) { 
mListeners.remove(listener); 
if (handler == null) { 
handler = mDefaultHandler; 
} 


mListeners.put(listener, handler); 


@Override 
public void unregisterInputDeviceListener(InputDeviceListener listener) 
mListeners.remove(listener); 


private void notifyListeners(int why, int deviceId) ( 
// the state of some device has changed 
if (!mListeners.isEmpty()) { 
for (InputDeviceListener listener : mListeners.keySet()) { 
Handler handler - mListeners.get(listener); 
DeviceEvent odc = DeviceEvent.getDeviceEvent(why, deviceld, 
listener); 

handler.post(odc); 


private static class DeviceEvent implements Runnable { 
private int mMessageType; 
private int mId; 
private InputDeviceListener mListener; 
private static Queue sObjectQueue - 
new ArrayDeque(); 


static DeviceEvent getDeviceEvent(int messageType, int id, 

InputDeviceListener listener) { 

DeviceEvent curChanged = sObjectQueue.poll(); 

if (null == curChanged) { 
curChanged = new DeviceEvent(); 

} 

curChanged.mMessageType = messageType; 

curChanged.mId = id; 

curChanged.mListener = listener; 

return curChanged; 


@Override 
public void run() { 
switch (mMessageType) { 
case ON_DEVICE_ADDED: 
mListener.onInputDeviceAdded(mId); 
break; 
case ON DEVICE CHANGED: 
mListener.onInputDeviceChanged(mId); 
break; 
case ON DEVICE REMOVED: 
mListener.onInputDeviceRemoved(mId); 
break; 
default: 
// Handle unknown message type 


break; 


j 


// Put this runnable back in the queue 
sObjectQueue.offer(this); 


我 们 现在 已 经 有 两 个 InputManagercompat 的 实现 : 一 个 可 以 在 运行 Android 4.1 或 者 更 高 版 
本 的 设备 上 工作 ， 另 一 个 可 以 在 运行 Android 2.3 到 ”Android 4.0 的 设备 上 工作 。 


使 用 特定 版 本 的 实现 
特定 版 本 切换 的 逻辑 是 在 一 个 充当 factory 的 类 中 实现 。 


public static class Factory { 
public static InputManagerCompat getInputManager(Context context) { 
if (Build.VERSION.SDK INT >= Build.VERSION CODES.JELLY BEAN) { 
return new InputManagerVi6(context); 
} else { 
return new InputManagerV9(); 


现在 我 们 可 以 简单 地 实例 化 一 个 InputManagercompat 对 象 ， 并 且 在 主 view 中 注册 
InputManagerCompat.InputDevicelistener 。 由 于 我 们 建立 的 版 本 切换 逻辑 ， 我 们 的 游戏 会 自 
动 为 设备 上 运行 的 Android 版 本 使 用 适当 的 实现 。 


public class GameView extends View implements InputDeviceListener { 
private InputManagerCompat mInputManager; 


public GameView(Context context, AttributeSet attrs) { 
mInputManager - 
InputManagerCompat.Factory.getInputManager(this.getContext()); 
mInputManager.registerInputDeviceListener(this, null); 


下 一 步 重 写 主 View 的 onGenericMotionEvent() 方法 ， 详 见 处 理 从 游戏 控制 器 传 来 的 
MotionEvent。 我 们 的 游戏 现在 应 该 可 以 一 致 地 处 理 运行 着 Android 2.3 (APllevel 9) 和 更 高 
版 本 设备 上 的 游戏 控制 器 事件 。 


@Override 
public boolean onGenericMotionEvent(MotionEvent event) { 
mInputManager .onGenericMotionEvent (event); 


// Handle analog input from the controller as normal 


return super.onGenericMotionEvent(event); 


我 们 可 以 在 上 述 的 controllersample.zip 示例 的 Gameview 类 中 找到 这 个 兼容 性 的 完整 的 代 
AU o 


支持 多 个 游戏 控制 器 


编写 :heray1990 - Æ X:http://developer.android.com/training/game-controllers/multiple- 


controllers.html 


尽管 大 部 分 的 游戏 都 被 设计 成 一 台 AAA 
台 Android 设备 上 同时 连接 的 多 个 游戏 控制 器 ( 即 多 个 用 户 ) 。 


这 节 课 覆盖 了 一 些 处 理 单个 设备 多 个 玩家 (或 者 多 个 控制 器 ) 输入 的 基本 技术 。 这 包括 维护 
一 个 在 玩家 化 身 和 每 个 控制 器 之 间 的 映射 ， 以 及 适当 eee 器 的 输入 事件 。 


映射 玩家 到 控制 器 的 设备 ID 


当 一 个 游戏 控制 器 连接 到 一 台 Android 设备 ， 系 统 会 为 控制 NE ipM ID » Af] 
可 以 通过 调用 inputDevice.getDevicerds() 来 取得 已 连接 的 游戏 控制 器 的 设备 ID， 如 验证 游 
戏 控制 器 是 否 已 连接 介绍 的 一 样 。 crams e 
别处 理 每 个 玩家 的 游戏 动作 。 


Note : 在 运行 着 Android 4.1 (APllevel 16) 或 者 更 高 版 本 的 设备 上 ， 我 们 可 以 通过 使 
用 getDescriptor() 来 取得 输入 设备 的 描述 符 。 上 述 函 数 为 输入 设备 返回 一 个 唯一 连续 
的 字符 串 值 。 不 同 于 设备 ID， 即 使 在 输入 设备 断 开 、 重 连 或 者 重新 配置 时 ， 描 述 符 都 不 


会 变化 。 


下 面 的 代码 介绍 了 如 何 使 用 SparseArray 来 关联 玩家 化 身 与 一 个 特定 的 控制 器 。 在 这 个 例子 
中 ，mships 变量 保存 了 一 个 ship 对 象 的 集合 。 当 一 个 新 的 控制 器 连接 到 一 个 用 户 时 ， 会 
创建 一 个 新 的 玩家 化 身 。 当 已 关联 的 控制 器 被 移 除 时 ， 对 应 的 玩家 化 身 会 被 移 除 。 


onInputDeviceAdded() 和 EERE 回调 函数 是 在 不 同 的 Android 系统 版 本 支 
持 控 制 器 中 介绍 的 抽象 层 的 一 部 分 。 通 过 实现 这 些 listener 回调 ， 我 们 的 游戏 可 以 在 添加 或 者 
移 除 控制 器 的 时 候 ， 识 别 出 游 戏 控制 器 的 设备 1D。 这 个 检测 兼容 Android 2.3 (API level 9) 
和 更 高 的 版 本 。 


private final SparseArray<Ship> mShips = new SparseArray<Ship>(); 


@Override 

public void onInputDeviceAdded(int deviceId) { 
getShipForID(devicelId); 

} 


@Override 
public void onInputDeviceRemoved(int deviceld) { 
removeShipForID(deviceId); 


} 


private Ship getShipForID(int shipID) { 
Ship currentShip - mShips.get(shipID); 
if ( null == currentShip ) { 
currentShip - new Ship(); 
mShips.append(shipID, currentShip); 
} 
return currentShip; 


} 


private void removeShipForID(int shipID) { 
mShips.remove(shipID); 


} 


处 理 乡 个 控制 器 输入 


我 们 的 游戏 应 该 执行 下 面 的 循环 来 处 理 多 个 控制 器 的 输入 : 
1.， 检测 是 否 出 现 一 个 输入 事件 。 
2. 识别 输入 源 和 它 的 设备 ID © 


3. 根据 以 输入 事件 按键 码 或 者 坐标 值 的 形式 表示 的 action， 更 新 玩家 化 身 与 设备 ID 的 关联 
关系 。 


4. 泻 当 和 更 新 用 户 界面 。 


keyEvent 和 MotionEvent 输入 事件 与 设备 ID 相关 联 。 我 们 的 游戏 可 以 利用 这 个 关联 来 确定 
输入 事件 从 哪个 控制 器 发 出 ， 并 且 更 新 玩家 化 身 与 控制 器 的 关联 。 


下 面 的 代码 介绍 了 我 们 如 何 将 一 个 玩家 化 身 引 用 相应 的 游戏 控制 器 设备 ID， 并 且 根 据 用 户 按 
下 控制 器 的 按键 来 更 新 游戏 。 





@Override 


public boolean onKeyDown(int keyCode, KeyEvent event) ( 
if ((event.getSource() & InputDevice.SOURCE GAMEPAD) 
-- InputDevice.SOURCE GAMEPAD) ( 
int deviceId = event.getDeviceId(); 
if (deviceId != -1) { 
Ship currentShip - getShipForId(deviceId); 
// Based on which key was pressed, update the player avatar 
// (e.g. set the ship headings or fire lasers) 


return tenue; 


} 
} 
return super.onKeyDown(keyCode, event); 
} 
Note: 一 个 最 佳 做 法 ， 当 用 户 的 游戏 控制 器 断 开 时 ， 我 们 应 该 停止 游戏 并 询问 用 户 是 否 


像 要 重新 连接 。 
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^h 5 :Kesenhoo - /$ X :http://developer.android.com/training/best-background.html 


下 面 的 这 些 课程 会 教 我 们 如 何 通过 把 任务 执行 在 后 台 线 程 来 提升 程序 的 性 能 ， 还 会 教 我 们 如 
何 最 小 化 后 台 线 程 对 电量 的 消耗 。 


在 后 台 Service 中 执行 任务 

学 习 如 何 通 过 发 送 任 务 给 后 台 Service 来 提升 UI 的 性 能 并 避免 ANR。 
在 后 台 加 载 数 据 

学 习 如 何 使 用 CursorLoader 来 查询 数据 ， 同 时 避免 影响 到 UI| 的 响应 性 
管理 设备 的 唤醒 状态 


学 习 如 何 使 用 重复 闹钟 以 及 唤醒 锁 来 执行 后 台 任 务 。 


在 IntentService 中 执行 后 台 任 务 


编写 :kesenhoo - 原文 :http://developer.android.com/training/run-background- 
service/index.html 


除非 我 们 特别 为 某 个 操作 指定 特定 的 线程 ， 否 则 大 部 分 T 台 UI 有 界面 上 的 操作 任务 都 执行 在 
一 个 叫做 UI Thread 的 特殊 线程 中 。 这 可 能 存在 某 些 隐 因为 部 分 在 UI 界 面 上 的 耗 时 操作 可 
能 会 影响 界面 的 响应 性 能 。 eee ， 甚 至 可 能 导致 系统 ANR 错 
误 。 为 了 避免 这 样 的 问题 ，Android Framework 提 供 了 几 个 类 ， 用 来 帮助 你 把 那些 耗 时 操作 移 

动 到 后 台 线 程 中 执行 。 那 些 类 中 最 常用 的 就 是 IntentService. 


这 一 章节 会 讲 到 如 何 实现 一 个 IntentService， 向 它 发 送 任 务 并 反馈 任务 的 结果 给 其 他 模块 。 


Demos 


ThreadSample.zip 


Lessons 


e 创建 IntentService 

学 习 如 何 创建 一 个 IntentService 。 
e 发 送 任务 请 求 给 IntentService 

学 习 如 何 发 送 工作 任务 给 IntentService ° 
e 报告 后 台 任 务 的 执行 状态 


学 习 如 何 使 用 Intent 与 LocalBroadcastManager 在 Activit 与 IntentService 之 间 进 行 交 互 。 


创建 后 全 服务 


编写 :kesenhoo - 原文 :http://developer.android.com/training/run-background- 
Service/create-service.html 


IntentService 为 在 单一 后 台 线 程 中 执行 任务 提供 了 一 种 直接 的 实现 方式 。 它 可 以 处 理 一 个 耗 时 
的 任务 并 确保 不 影响 到 UI 的 响应 性 。 另 外 IntentService 的 执行 还 不 受 U| 生 命 周 期 的 影响 ， 以 此 
来 确保 AsyncTask 能 够 顺利 运行 。 


但 是 IntentService 有 下 面 几 个 局 限 性 : 


e. 不 可 以 直接 和 UI 做 交互 。 为 了 把 他 执行 的 结果 体现 在 UI 上 ， 需 要 把 结果 返回 给 Activity © 

e 工作 任务 队列 是 顺序 执行 的 ， 如 果 一 个 任务 正在 IntentService 中 执行 ， 此 时 你 再 发 送 一 个 
新 的 任务 请 求 ， 这 个 新 的 任务 会 一 直 等 待 直到 前 面 一 个 任务 执行 完毕 才 开 始 执行 。 

。 正在 执行 的 任务 无 法 打 断 。 


虽然 有 上 面 那些 限制 ， 然 而 在 在 大 多 数 情况 下 ，lntentService 都 是 执行 简单 后 台 任务 操作 的 理 
想 选择 。 


这 节 课 会 演示 如 何 创建 继承 的 IntentService。 同 样 也 会 演示 如 何 创建 必须 的 回调 方 
法 onHandleIntent() 。 最 后 ， 还 会 解释 如 何在 manifest 文 件 中 定义 这 个 IntentService 。 


1) 创 建 IntentService 


为 你 的 app 创 建 一 个 IntentService 组 件 ， 需 要 自 定义 一 个 新 的 类 ， 它 继承 自 IntentService， 并 
重 写 onHandlelntent() 方 法 ， 如 下 所 示 : 


public class RSSPullService extends IntentService { 
@Override 
protected void onHandleIntent(Intent workIntent) { 
// Gets data from the incoming Intent 
String dataString = workIntent.getDataString(); 


// Do work here, based on the contents of dataString 


注意 一 个 普通 Service 组 件 的 其 他 回调 ， 例 如 onstartcommand() 会 被 IntentService 自 动 调用 。 
在 IntentService 中 ， 要 避免 重 写 那些 回调 。 


2)& Manifest x 1+ X 3 IntentService 


IntentService 需 要 在 manifest 文 件 添加 相应 的 条 目 ， 将 此 条 目 service» 作 
为 <application> 元 素 的 子 元 素 下 进行 定义 ， 如 下 所 示 : 


«application 
android:icon-"Qdrawable/icon" 
android: label="@string/app_name"> 


Because android:exported is set to "false", 
the service is only available to this app. 


SS. 


<service 
android:namez".RSSPullService" 
android:exported-"false"/» 


«application/» 


android:name 属性 指明 了 IntentService 的 名 字 。 


注意 «service» 标签 并 没有 包含 任何 intent filter。 因 为 发 送 任务 给 IntentService 的 Activity 需 要 
使 用 显 式 Intent， 所 以 不 需要 filter。 这 也 意味 着 只 有 在 同一 个 app 或 者 其 他 使 用 同一 个 UserlD 
的 组 件 才 能 够 访问 到 这 个 Service 。 


至 此 ， 你 已 经 有 了 一 个 基本 的 IntentService 类 ， 你 可 以 通过 构造 Intent 对 象 向 它 发 送 操作 请 
求 。 构 造 这 些 对 象 以 及 发 送 它们 到 你 的 IntentService 的 方式 ， 将 在 接 下 来 的 课程 中 描述 。 


向 后 台 服 务 发 送 任务 请 


编写 :kesenhoo - 原文 :http://developer.android.com/training/run-background- 


service/send-request.html 


前 一 篇 文章 演示 了 如 何 创建 一 个 IntentService 类 。 这 次 会 演示 如 何 通过 发 送 一 个 Intent 来 触发 
IntentService 执 行 任 务 。 这 个 Intent 可 以 传递 一 些 数据 给 IntentService。 我 们 可 以 在 Activity 或 
者 Fragment 的 任何 时 间 点 发 送 这 个 Intent 。 


创建 任务 请 求 并 发 送 到 IntentService 


为 了 创建 一 个 任 ee 。 需 要 先 创建 一 个 显 式 Intent， 并 将 请 求 数 据 添 
加 到 intent 中 ， 然 后 通过 调用 startservice() 方法 把 任务 请 求 数据 发 送 到 IntentService ° 


下 面 的 是 代码 示例 : 


创建 一 个 新 的 显 式 Intent 用 来 启动 IntentService » 


/* 
* Creates a new Intent to start the RSSPullService 

* IntentService. Passes a URI in the 

‘ntentis "data" field: 

aif 

mServicelntent = new Intent(getActivity(), RSSPullService.class); 


mServiceIntent.setData(Uri.parse(dataUrl)); 


e 执行 startService() 


// Starts the IntentService 
getActivity().startService(mServiceIntent); 


注意 可 以 在 Activity 或 者 Fragment 的 任何 位 置 发 送 任 务 请 求 。 例 如 ， 如 果 你 先 获取 用 户 输入 ， 
您 可 以 从 响应 按钮 单 击 或 类 似 手势 的 回调 方法 里 面 发 送 任 务 请 求 。 


一 旦 执行 了 startService()， IntentService 在 自己 本 身 的 onHandleIntent() 方法 里 面 开始 执行 这 
个 任务 ， 任 务 结束 之 后 ， 会 自动 停止 这 个 Service。 


下 一 步 是 如 何 把 工作 任务 的 执行 结果 返回 给 REM 或 者 Fragment。 下 节 课 会 演示 
如 何 使 用 BroadcastReceiver 来 完成 这 个 任务 


发 送 工作 任务 到 IntentService 
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报告 任务 执行 状态 


编写 :kesenhoo - Æ x-:http://developer.android.com/training/run-background- 
service/report-status.html 


这 章节 会 演示 AAS 。 例 如 ， 回 传 任务 的 
执行 状态 给 Activity 并 进行 更 新 Ul。 推 荐 的 方式 是 使 用 LocalBroadcastManager， 这 个 组 件 可 
以 限制 broadcast intent 只 在 自己 的 app 中 进行 传递 。 


利用 IntentService 发 送 任务 状态 


为 了 在 IntentService 中 向 其 他 组 件 发 送 任务 状态 ， 首 先 创建 一 个 Intent 并 在 data 字 段 中 包含 需 
要 传递 的 信息 。 作 为 一 个 可 选项 ， 还 可 以 给 这 个 Intent 添 加 一 个 action 与 data URI ° 


下 一 步 ， 通 过 执行 LocalBroadcastManager.sendBroadcast() 来 发 送 Intent。lIntent 被 发 送 到 任何 
有 注册 接受 它 的 组 件 中 。 为 了 获取 到 LocalBroadcastManager 的 实例 ， 可 以 执行 
getlnstance()。 代 码 示 例如 下 : 


public final class Constants { 


// Defines a custom Intent action 
public static final String BROADCAST ACTION - 
"com.example.android.threadsample.BROADCAST"; 


// Defines the key for the status "extra" in an Intent 
public static final String EXTENDED DATA STATUS - 
"com.example.android.threadsample.STATUS"; 


} 


public class RSSPullService extends IntentService { 


/* 

* Creates a new Intent containing a Uri object 

* BROADCAST ACTION is a custom Intent action 

E 

Intent localIntent = 
new Intent(Constants.BROADCAST_ACTION) 
// Puts the status into the Intent 
.putExtra(Constants.EXTENDED DATA STATUS, status); 

// Broadcasts the Intent to receivers in this app. 

LocalBroadcastManager.getInstance(this).sendBroadcast(localIntent); 


下 一 步 是 在 发 送 任务 的 组 件 中 接收 发 送出 来 的 broadcast 数 据 。 


接收 来 自 IntentService 的 状态 广播 


为 了 接受 广播 的 数据 对 象 ， 需 要 使 用 BroadcastReceiver 的 子 类 并 实 
现 BroadcastReceiver.onReceive() 的 方法 ， 这 里 可 以 接收 LocalBroadcastManager 发 出 的 广 
播 数据 。 


// Broadcast receiver for receiving status updates from the IntentService 
private class ResponseReceiver extends BroadcastReceiver 


{ 


// Prevents instantiation 
private DownloadStateReceiver() ( 


} 


// Called when the BroadcastReceiver gets an Intent it's registered to receive 


@ 
public void onReceive(Context context, Intent intent) 1 
Jf 
* Handle Intents here. 
E 


NL 3. J BroadcastReceiver > 45, A XX 3Lactions > categories data/f] tr 4& » ATS 
xanh 


// Class that displays photos 
public class DisplayActivity extends FragmentActivity { 


public void onCreate(Bundle stateBundle) { 
super.onCreate(stateBundle); 
// The filter's action is BROADCAST ACTION 
IntentFilter mStatusIntentFilter - new IntentFilter( 


Constants.BROADCAST ACTION); 


// Adds a data filter for the HTTP scheme 
mStatusIntentFilter.addDataScheme("http"); 


为 了 给 系统 注册 这 个 BroadcastReceiver 和 |ntentFilter > 3; 34 3t LocalBroadcastManager4 
行 registerReceiver() 的 方法 。 如 下 所 示 : 


// Instantiates a new DownloadStateReceiver 
DownloadStateReceiver mDownloadStateReceiver - 
new DownloadStateReceiver(); 
// Registers the DownloadStateReceiver and its intent filters 
LocalBroadcastManager.getInstance(this).registerReceiver( 
mDownloadStateReceiver, 
mStatusIntentFilter); 


一 个 BroadcastReceiver 可 以 处 理 多 种 类 型 的 广播 数据 。 每 个 广播 数据 都 有 自己 的 ACTION 。 
这 个 功能 使 得 不 用 定义 多 个 不 同 a 他 别处 理 不 同 的 ACTION 数 据 。 为 
BroadcastReceiver 定 义 另 外 一 个 IntentFilter， 只 需要 创建 一 个 新 的 IntentFilter 并 重复 执行 
registerReceiver()?? T » 45] 3e 


* Instantiates a new action filter. 
* No data filter is needed. 
*/ 
statusIntentFilter - new IntentFilter(Constants.ACTION ZOOM IMAGE); 


// Registers the receiver with the new filter 
LocalBroadcastManager.getInstance(getActivity()).registerReceiver( 
mDownloadStateReceiver, 
mIntentFilter); 


发 送 一 个 广播 Intent 并 不 会 启动 或 重启 一 个 Activity » T 的 app 在 后 台 运 行 ， rudi 
BroadcastReceiver 也 可 以 接收 、 处 理 Intent 对 象 。 但 是 这 不 会 迫使 你 的 app 进 入 前 当 你 的 
app 不 可 见 时 ， 如 果 想 通知 用 户 一 个 发 生 在 后 台 的 事件 ， Ms Notification ° zk M Jy 
响应 一 个 广播 Intent 而 去 启动 Activity。 


使 用 CursorLoader 在 后 台 加 载 数 据 


编写 :kesenhoo - 原文 :http://developer.android.com/training/load-data- 
background/index.html 


从 ContentProvider 查 询 你 需要 显示 的 数据 是 比较 耗 时 的 。 如 果 你 在 Activity 中 直接 执行 查询 的 
操作 ， 那 么 有 可 能 导致 Activity 出 现 ANR 的 错误 。 即 使 没有 发 生 ANR， 用 户 也 容易 感知 到 一 个 
令 人 烦恼 的 UI 卡 顿 。 为 了 避免 那些 问题 ， 你 应 该 在 另外 一 个 线程 中 执行 查询 的 操作 ， 等 待 查 
询 操 作 完 成 ， 然 后 再 显示 查询 结果 。 


时 自动 执行 重新 查询 的 操作 。 


这 节 课 会 介绍 如 何 使 用 CursorLoader 来 执行 一 个 后 台 查 询 数据 的 操作 。 在 这 节 课 中 的 演示 代 
码 使 用 的 是 v4 Support Library 中 的 类 。 


Demos 


ThreadSample 


Lessons 


e 使 用 CursorLoader 执 行 查询 任务 
学 习 如 何 使 用 CursorLoader 在 后 台 执 行 查询 操作 。 
e 处 理 CursorLoader 查 询 的 结果 


学 习 如 何 处 理 从 CursorLoader 查 询 到 的 数据 ， 以 及 在 loader 框 架 重 置 CursorLoader 时 如 
何 解除 当前 Cursor 的 引用 。 


使 用 CursorLoader 执 行 查询 任务 


编写 :kesenhoo - 原文 :http://developer.android.com/training/load-data- 


background/setup-loader.html 


CursorLoader 通 过 ContentProvider 在 后 台 执 行 一 个 异步 的 查询 操作 ， 并 且 返 回 数据 给 调用 它 
i umen 这 使 得 Activity 或 者 FragmentActivity 能 够 在 查询 任务 正在 执 
行 的 同时 继续 与 用 户 进行 其 他 的 交互 操作 。 


定义 使 用 CursorLoader 的 Activity 


为 了 在 Activity 或 者 FragmentActivity 中 使 用 CursorLoader， 它 们 需要 实 
现 LoaderCallbacks<Cursor> 接口 。CursorLoader 会 调用 Loadercallbacks<Cursor> 定义 的 这 些 
回调 方法 与 Activity 进 行 交 互 ; 这 这 节 课 与 下 节 课 会 详细 介绍 每 一 个 回调 方法 。 


例如 ， 下 面 演示 了 FragmentActivity 如 何 使 用 CursorLoader。 


public class PhotoThumbnailFragment extends FragmentActivity implements 
LoaderManager .LoaderCallbacks<Cursor> { 


初始 化 查询 


为 了 初始 化 查询 ， 需 要 调用 LoaderManager.initLoader() ° 这 个 方法 可 以 初始 化 
LoaderManager 的 后 台 查 询 框架 。 你 可 以 在 用 户 输入 查询 条 件 之 后 触发 初始 化 的 操作 ， 如 果 
你 不 需要 用 户 输入 数据 作为 查询 条 件 ， 你 可 以 在 onCreate() 或 者 onCreateView() 里 面 触 发 这 
个 方法 。 例 如 


使 用 CursorLoader 执 行 查询 在 


// Identifies a particular Loader being used in this component 
private static final int URL LOADER = 0; 


/* When the system is ready for the Fragment to appear, this displays 
* the Fragment's View 
i 
public View onCreateView( 
LayoutInflater inflater, 
ViewGroup viewGroup, 
Bundle bundle) { 
PES 
* Initializes the CursorLoader. The URL LOADER value is eventually passed 
* to onCreateLoader( ). 
i 
getLoaderManager().initLoader(URL LOADER, null, this); 


Note: getLoaderManager() 仅仅 是 在 Fragment 类 中 可 以 直接 访问 。 为 了 在 
FragmentActivity 中 获取 到 LoaderManager， 需 要 执行 getSupportLoaderManager() . 


开始 查询 


一 旦 后 台 任务 被 初始 化 好 ， 它 会 执行 你 实现 的 回调 方法 oncreateLoader() 。 为 了 局 动 查询 任 
， 会 在 这 个 方法 里 面 返回 CursorLoader 。 你 可 以 初始 化 一 个 空 的 CursorLoader 然 后 使 用 它 
的 方法 来 定义 你 的 查询 条 件 ， 或 者 你 可 以 在 初始 化 CursorLoader 对 象 的 时 候 就 同时 定义 好 查 
WA: 


we 
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使 用 CursorLoader 执 行 查 询 任务 


Callback that's invoked when the system has initialized the Loader and 
is ready to start the query. This usually happens when initLoader() is 
called. The loaderID argument contains the ID value passed to the 

* initLoader() call. 


24 
@Override 
public Loader<Cursor> onCreateLoader(int loaderID, Bundle bundle) 
{ 
/* 
* Takes action based on the ID of the Loader that's being created 
Lyf 
switch (loaderID) { 
case URL_LOADER: 
// Returns a new CursorLoader 
return new CursorLoader( 
getActivity(), // Parent activity context 
mDataUurl, // Table to query 
mProjection, // Projection to return 
null, // No selection clause 
null, // No selection arguments 
null // Default sort order 
); 
default: 
// An invalid id was passed in 
return null; 
} 
} 


一 旦 后 人 台 查 询 任 务 获取 到 了 这 个 Loader 对 和 象 ， 就 开始 在 后 台 执 行 查询 的 任务 。 当 查询 完成 之 
后 ， 会 执行 onLoadFinished() 这 个 回调 函数 ， 关 于 这 些 内 容 会 在 下 一 节 讲 到 。 
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处 理 查询 的 结果 


编写 :kesenhoo - 原文 :http://developer.android.com/training/load-data- 
background/handle-results.html 


正如 前 面 一 节 课 讲 到 的 ， 你 应 该 在 onCreateLoader() 的 回调 里 面 使 用 CursorLoader 执 行 加 载 
数据 的 操作 。Loader 查 询 完 后 会 调用 Activity 或 者 FragmentActivity 的 
LoaderCallbacks.onLoadFinished() 将 结果 回调 回来 。 这 个 回调 方法 的 参数 之 一 是 Cursor， 它 
包含 了 查询 的 数据 。 你 可 以 使 用 Cursor 对 象 来 更 新 需要 显示 的 数据 或 者 进行 下 一 步 的 处 理 。 


除了 onCreateLoader() 与 onLoadFinished()， 你 也 需要 实现 onLoaderReset()。 这 个 方法 在 
CursorLoader 检 测 到 Cursor 上 的 数据 发 生变 化 的 时 候 会 被 触发 。 当 数据 发 生变 化 时 ， 系 统 也 
会 触发 重新 查询 的 操作 。 


处 理 查 询 结 果 


为 了 显示 CursorLoader 返 回 的 Cursor 数 据 ， 需 要 使 用 实现 AdapterView 的 视图 组 件 ，， 并 为 这 
个 组 件 绑 定 一 个 实现 了 CursorAdapter 的 Adapter。 系 统 会 自动 把 Cursor 中 的 数据 显示 到 View 
iX 


你 可 以 在 显示 数据 之 前 建立 View 与 Adapter 的 关联 。 然 后 在 onLoadFinished() 的 时 候 把 Cursor 
与 Adapter 进 行 绑 定 。 一 旦 你 把 Cursor 与 Adapter 进 行 绑 定 之 后 ， 系 统 会 自动 更 新 View。 当 
Cursor 上 的 内 容 发 生 改 变 的 时 候 ， 也 会 触发 这 些 操作 。 


例如 : 


public String[] mFromColumns = { 
DataProviderContract.IMAGE PICTURENAME COLUMN 
HN 
public int[] mToFields - ( 
R.id.PictureName 
HN 
// Gets a handle to a List View 
ListView mListView - (ListView) findViewById(R.id.dataList); 
/* 
* Defines a SimpleCursorAdapter for the ListView 
i 
SimpleCursorAdapter mAdapter - 
new SimpleCursorAdapter ( 


this, // Current context 
R.layout.list item, // Layout for a single row 
null, // No Cursor yet 
mFromColumns, // Cursor columns to use 
mToFields, // Layout fields to use 

0 // No flags 


); 

// Sets the adapter for the view 
mListView. setAdapter (mAdapter ); 
Vin 

* Defines the callback that CursorLoader calls 

* when it's finished its query 

rA 
@Override 

public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) { 


ES 
* Moves the query results into the adapter, causing the 
* ListView fronting this adapter to re-display 
i 

mAdapter.changeCursor(cursor); 


Al A E a 49 Cursor] 用 


当 Cursor 失 效 的 时 候 ，CursorLoader 会 被 重 置 。 这 通常 发 生 在 Cursor 相 关 的 数据 改变 的 时 

候 。 在 重新 执行 查询 操作 之 前 ， 系 统 会 执行 你 的 onLoaderReset() 回 调 方法 。 在 这 个 回调 方法 
中 ， 你 应 该 删除 当前 Cursor 上 的 所 有 数据 ， 避 免 发 生 内 存 泄露 。 一 旦 onLoaderReset() 执 行 结 
束 ，CursorLoader 就 会 重新 执行 查询 操作 。 


例如 : 


处 理 CursorLoader 查 询 的 结果 


Ue 
* Invoked when the CursorLoader is being reset. For example, this is 
* called if the data in the provider changes and the Cursor becomes stale. 
4 

@Override 

public void onLoaderReset(Loader<Cursor> loader) { 


Jis 
“Clears out the adapteris neference to the Cursor. 
* This prevents memory leaks. 
54 

mAdapter.changeCursor(null); 
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管理 设备 的 唤醒 状态 


编写 :jdneo，Ittowdqd - 原文 :http://developer.android.com/training/scheduling/index.html 


当 一 个 Android 设 备 闲 置 时 ， 首 先 它 的 屏幕 将 会 变 暗 ， 然 后 关闭 屏幕 ， 最 后 关闭 CPU 。 这 样 可 
以 防止 设备 的 电量 被 迅速 消耗 殉 尽 。 但 是 ， 有 时 候 也 会 存在 一 些 特例 : 


e 例如 游戏 或 视频 应 用 需要 保持 屏幕 常 亮 ; 
e 其 它 应 用 也 许 不 需要 屏幕 常 亮 ， 但 或 许 会 需要 CPU 保 持 运行 ， 直 到 茶 个 关键 操作 结 


这 节 课 描述 如 何在 必要 的 时 候 保持 设备 唤醒 ， 同 时 又 不 会 过 多 消耗 它 的 电量 。 


Demos 


Scheduler.zip 


Lessons 
保持 设备 唤醒 
学 习 如 何在 必要 的 时 候 保 持 屏 幕 和 CPU 唤醒 ， 同 时 减少 对 电池 寿命 的 影响 。 
HA EZ iE 


对 于 那些 发 生 在 应 用 生命 周期 之 外 的 操作 ， 学 习 如 何 使 用 重复 闵 钟 对 它们 进行 调度 ， 即 使 该 
应 用 没有 运行 或 者 设备 处 于 睡眠 状态 。 


保持 设备 唤醒 


编写 :jdneo - 原文 :http://developer.android.com/training/scheduling/wakelock.html 


为 了 避免 电量 过 度 消耗 ，Android 设 备 会 在 被 闲置 之 后 迅速 进入 睡眠 状态 。 然 而 有 时 候 应 用 会 
需要 唤醒 屏幕 或 者 是 唤醒 CPU 并 且 保 持 它们 的 唤醒 状态 ， 直 至 一 些 任务 被 完成 。 


想 要 做 到 这 一 点 ， 所 采取 的 方法 依赖 于 应 用 的 具体 需求 。 但 是 通常 来 说 ， 我 们 应 该 使 用 最 轻 
量 级 的 方法 ， 减 小 其 对 系统 资源 的 影响 。 在 接 下 来 的 部 分 中 ， 我 们 将 会 描述 在 设备 默认 的 睡 
眠 行为 与 应 用 的 需求 不 相符 合 的 情况 下 ， 我 们 应 该 如 何 进 行 对 应 的 处 理 。 


保持 屏幕 第 完 


某 些 应 用 需要 保持 屏幕 常 亮 ， 比 如 游戏 与 视频 应 用 。 最 好 的 方式 是 在 你 的 Activity 中 〈 且 仅 在 
Activity 中 ， 而 不 是 在 Service 或 其 他 应 用 组 件 里 ) 使 用 FLAG KEEP SCREEN ON&# > 6 
如 : 


public class MainActivity extends Activity { 
@Override 
protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
setContentView(R.layout.activity main); 
getwindow().addFlags(WindowManager.LayoutParams.FLAG KEEP SCREEN ON); 
n 


该 方法 的 优点 与 唤醒 锁 (Wake Locks) 不 同 (唤醒 锁 的 内 容 在 本 章节 后 半 部 分 ) ， 它 不 需要 
任何 特殊 的 权限 ， 系 统 会 正确 地 管理 应 用 之 间 的 切换 ， 且 不 必 关 心 释放 资源 的 问题 。 


另外 一 种 方法 是 在 应 用 的 XML 布局 文件 里 ， 使 用 android:keepScreenOn 属 性 : 


<RelativeLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:layout width-"match parent" 
android:layout height-"match parent" 
android: keepScreenOn="true"> 


</RelativeLayout> 
使 用 android: keepScreenon="true" 与 使 用 FLAG KEEP _SCRRE_ON 等 效 。 你 可 以 选择 最 适 


& 
合 你 的 应 用 的 方法 。 在 Activity 中 通过 代码 设置 常 亮 标识 的 优点 在 于 : 你 可 以 通过 代码 动态 清 
除 这 个 标示 ， 从 而 使 屏幕 可 以 关闭 。 


Notes : 除非 你 不 再 希望 正在 运行 的 应 用 长 时 间 点 亮 屏幕 〈 例 如 : 在 一 定时 间 无 操作 发 生 
后 ， 你 想 要 将 屏幕 关闭 ) ， 否 则 你 是 不 需要 清除 FLAG_KEEP_SCRRE_ON 标识 的 。 
WindowManager 会 在 应 用 进入 后 台 或 者 返回 前 台 时 ， 正 确 管理 屏幕 的 点 亮 或 者 关闭 。 但 
是 如 果 你 想 要 显 式 地 清除 这 一 标识 ， 从 而 使 得 屏幕 能 够 关闭 ， 可 以 使 


用 getwindow().clearFlags(WindowManager.LayoutParams.FLAG KEEP SCREEN ON) 方法 。 


保持 CPU 运行 


如 果 你 需要 在 设备 睡眠 之 前 ， 保 持 CPU 运 行 来 完成 一 些 工 作 ， 你 可 以 使 用 PowerManager 系 统 
服务 中 的 唤醒 锁 功 能 。 唤 醒 锁 人 允许 应 用 控制 设备 的 电源 状态 。 


创建 和 保持 唤醒 锁 会 对 设备 的 电源 寿命 产生 巨大 影响 。 因 此 你 应 该 仅 在 你 确实 需要 时 使 用 唤 
醒 锁 ， 且 使 用 的 时 间 应 该 越 短 越 好 。 如 果 想 要 在 Activity 中 使 用 唤醒 锁 就 显得 没有 必要 了 。 如 
上 所 述 ， 可 以 在 Activity 中 使 用 FLAG_KEEP_SCRRE _ON 让 屏幕 保持 常 亮 。 


使 用 唤醒 锁 的 一 种 合理 情况 可 能 是 : 一 个 后 人 台 服 务 需要 在 屏幕 关闭 时 利用 唤醒 锁 保持 CPU 运 
行 。 再 次 强调 ， 应 该 尽 可 能 规避 使 用 该 方法 ， 因 为 它 会 影响 到 电池 寿命 。 


不 必 使 用 唤醒 锁 的 情况 : 


1. 如果 你 的 应 用 正在 执行 一 个 HTTP 长 连接 的 下 载 任务 ， 可 以 考虑 使 
用 DownloadManager。 

2. 如 果 你 的 应 用 正在 从 一 个 外 部 服务 器 同步 数据 ， 可 以 考虑 创建 一 个 SyncAdapter 

3. 如 果 你 的 应 用 需要 依赖 于 某 些 后 台 服 务 ， 可 以 考虑 使 用 RepeatingAlarm 或 者 Google 
Cloud Messaging， 以 此 每 隔 特 定 的 时 间 ， 将 这 些 服 务 激活 。 


为 了 使 用 唤醒 锁 ， 首 先 需 要 在 应 用 的 Manifest 清 单 文件 中 增加 WAKE _ LOCK 权限 : 


«uses-permission android:name-"android.permission.WAKE LOCK" /» 


如 果 你 的 应 用 包含 一 个 BroadcastReceiver 并 使 用 Service 来 完成 一 些 工作 ， 你 可 以 通过 
WakefulBroadcastReceiver 管 理 你 唤醒 锁 。 后 续 章 节 中 将 会 提 到 ， 这 是 一 种 推荐 的 方法 。 如 
果 你 的 应 用 不 满足 上 述 情况 ， 可 以 使 用 下 面 的 方法 直接 设置 唤醒 锁 : 


PowerManager powerManager = (PowerManager) getSystemService(POWER SERVICE); 

Wakelock wakeLock = powerManager.newWakeLock(PowerManager.PARTIAL WAKE LOCK, 
"MyWakelockTag"); 

wakeLock.acquire(); 


可 以 调用 wakelock.release() 来 释放 唤醒 锁 。 当 应 用 使 用 完毕 时 ， 应 该 释放 该 唤醒 锁 ， 以 避 
免 电 量 过 度 消 耗 。 


使 用 WakefulBroadcastReceiver 


你 可 以 将 BroadcastReceiver 和 Service 结 合 使 用 ， 以 此 来 管理 后 台 任 务 的 生命 周 

期 。WakefulBroadcastReceiver 是 一 种 特殊 的 BroadcastReceiver， 它 专注 于 创建 和 管理 应 用 
的 PARTIAL_WAKE_LOCK。WakefulBroadcastReceiver 会 将 任务 交付 给 Service (一 般 会 是 
一 个 IntentService) ， 同 时 确保 设备 在 此 过 程 中 不 会 进入 睡眠 状态 。 如 果 在 该 过 程 当 中 没有 保 
持 住 唤醒 锁 ， 那 么 还 没 等 任务 完成 ， 设 备 就 有 可 能 进入 睡眠 状态 了 。 其 结果 就 是 : 应 用 可 能 
会 在 未 来 的 某 一 个 时 间 节 点 才 把 任务 完成 ， 这 显然 不 是 你 所 期 望 的 。 


要 使 用 WakefulBroadcastReceiver， 首 先 在 Manifest 文 件 添加 一 个 标签 : 


«receiver android:name=".MyWakefulReceiver"></receiver> 


下 面 的 代码 通过 startwakefulService() 启动 MyIntentService ° 该 方法 和 startService() 类 
似 ， 除 了 WakeflBroadcastReceiver 会 在 Service 启 动 后 将 唤醒 锁 保 持 住 。 传 北 
给 startwakefulservice() 的 Intent 会 携带 有 一 个 Extra 数 据 ， 用 来 标识 唤醒 锁 。 


public class MyWakefulReceiver extends WakefulBroadcastReceiver { 


QOverride 
public void onReceive(Context context, Intent intent) { 


// Start the service, keeping the device awake while the service is 
// launching. This is the Intent to deliver to the service. 

Intent service - new Intent(context, MyIntentService.class); 
startWakefulService(context, service); 


当 Service 结 束 之 后 ， 它 会 调用 mywakefulReceiver.completewakefulintent() 来 释放 唤醒 
锁 。 completewakefulIntent() 方法 中 的 Intent 参 数 是 和 WakefulBroadcastReceiver 传 递 进来 的 
Intent 参 数 一 致 的 : 


ILON R LÀ ga 
保持 设备 的 唤醒 


public class MyIntentService extends IntentService { 

public static final int NOTIFICATION ID - 1; 

private NotificationManager mNotificationManager; 

NotificationCompat.Builder builder; 

public MyIntentService() { 
super("MyIntentService"); 

} 

@Override 

protected void onHandleIntent(Intent intent) { 
Bundle extras = intent.getExtras(); 
// Do the work that requires your app to keep the CPU running. 
72/1 
// Release the wake lock provided by the WakefulBroadcastReceiver. 
MyWakefulReceiver.completewWakefullIntent(intent); 
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` = 万 一 s 
调度 重复 的 闹钟 
编写 :jdneo - 原文 :http://developer.android.com/training/scheduling/alarms.html 


Asr (基于 AlarmManager 类 ) 给 予 你 一 种 在 应 用 使 用 期 之 外 执行 与 时 间 相 关 的 操作 的 方法 。 
你 可 以 使 用 阅 钟 初始 化 一 个 长 时 间 的 操作 ， 例 如 每 天 开启 一 次 后 台 服 务 ， 下 载 当 日 的 天 气 预 
报 。 


闲 钟 具有 如 下 特性 : 


e 允许 你 通过 预 设 时 间或 者 设 定 某 个 时 间 间 隔 ， 来 触发 Intent ; 

e 你 可 以 将 它 与 BroadcastReceiver 相 结合 ， 来 启动 服务 并 执行 其 他 操作 ; 

e 可 在 应 用 范围 之 外 执行 ， 所 以 你 可 以 在 你 的 应 用 没有 运行 或 设备 处 于 睡眠 状态 的 情况 
下 ， 使 用 它 来 触发 事件 或 行为 ; 

e 帮助 你 的 应 用 最 小 化 资源 需求 ， 你 可 以 使 用 益 钟 调度 你 的 任务 ， 来 替代 计时 器 或 者 长 时 
间 连 续 运 行 的 后 台 服 务 。 


Note: 对 于 那些 需要 确保 在 应 用 使 用 期 之 内 发 生 的 定时 操作 ， 可 以 使 用 闹钟 替代 使 
用 Handler 结 合 Timer 与 Thread 的 方法 。 因 为 它 可 以 让 Android 系 统 更 好 地 统筹 系统 资源 。 


Ax Hi Fil HE 
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择 ， 特 别 是 当 你 想 要 触发 网 络 操 作 的 时 候 。 设 计 不 佳 的 闹钟 会 导致 电量 快速 耗 尽 ， 而 且 会 对 
服务 端 产生 巨大 的 负荷 。 


当 我 们 从 服务 端 同步 数据 时 ， 往 往 会 在 应 用 不 被 使 用 的 时 候 时 被 唤醒 触发 执行 某 些 操作 。 此 
时 你 可 能 希望 使 用 重复 闹钟 。 但 是 如 果 存 储 数 据 的 服务 端 是 由 你 控制 的 ， 使 用 Google Cloud 
Messaging (GCM) 结合 sync adapter 是 一 种 更 好 解决 方案 。SyncAdapter 提 供 的 任务 调度 选 
项 和 AlarmManager 基 本 相同 ， 但 是 它 能 提供 更 多 的 灵活 性 。 比 如 : 同步 的 触发 可 能 基于 一 
条 “新 数据 "提示 消息 ， 而 消息 的 产生 可 以 基于 服务 器 或 设备 ， 用户 的 操作 (或 者 没有 操作 ) > 


KE KE 


每 天 的 某 一 时 刻 等 等 。 


最 佳 实践 方法 


在 设计 重复 阐 钟 过 程 中 ， 你 所 做 出 的 每 一 个 决定 都 有 可 能 影响 到 你 的 应 用 将 会 如 何 使 用 系统 
资源 。 例 如 ， 我 们 假想 一 个 会 从 服务 器 同步 数据 的 应 用 。 同 步 操作 基于 的 是 时 钟 时间 ， 具 体 
来 说 ， 每 一 个 应 用 的 实例 会 在 下 午 十 一 点 整 进行 同步 ， 巨 大 的 服务 器 负荷 会 导致 服务 器 响应 
时 间 变 长 ， 甚 至 拒绝 服务 。 因 此 在 我 们 使 用 闹钟 时 ， 请 牢记 下 面 的 最 佳 实践 建议 : 


对 任何 由 重复 闵 钟 触发 的 网 络 请 求 添加 一 定 的 随机 性 (抖动) 

o 在 闹钟 触发 时 做 一 些 本 地 任务 。" 本 地 任务 " 指 的 是 任何 不 需要 访问 服务 器 或 者 从 服务 

器 获取 数据 的 任务 ; 

o 同时 对 于 那些 包含 有 网 络 请 求 的 闹钟 ， 在 调度 时 机 上 增加 一 些 随 机 性 。 
尽量 让 你 的 闹钟 频率 最 小 ; 
如 果 不 是 必要 的 情况 ， 不 要 唤醒 设备 〈 这 一 点 与 闹钟 的 类 型 有 关 ， 本 节 课 后 续 部 分 会 提 
到 ) 
触发 闹钟 的 时 间 不 必 过 度 精 确 ; 尽量 使 用 setInexactRepeating() 方法 替 
代 setRepeating() 方法 。 当 你 使 用 setInexactRepeating() 方法 时 ，Android 系 统 会 集中 
多 个 应 用 的 重复 闹钟 同步 请 求 ， 并 一 起 触发 它们 。 这 可 以 减少 系统 将 设备 唤醒 的 总 次 
数 ， 以 此 减少 电量 消耗 。 从 Android 4.4 (API Level19) 开始 ， 所 有 的 重复 闹钟 都 将 是 非 
精确 型 的 。 注 意 虽然 setInexactRepeating() 是 setRepeating() 的 改进 版 本 ， 它 依然 可 能 
会 导致 每 一 个 应 用 的 实例 在 某 一 时 间 段 内 同时 访问 服务 器 ， 造 成 服务 器 负荷 过 重 。 因 此 
如 之 前 所 述 ， 对 于 网 络 请 求 ， 我 们 需要 为 闹钟 的 触发 时 机 增加 随机 性 。 
尽量 避免 让 曾 钟 基于 时 钟 时 间 。 


想 要 在 某 一 个 精确 时 刻 触 发 重复 闹钟 是 比较 困难 的 。 我 们 应 该 尽 可 能 使 
用 ELAPSED REALTIME 。 不 同 的 闹钟 类 型 会 在 本 节 课 后 半 部 分 展开 。 


设 
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如 上 所 述 ， 对 于 定期 执行 的 任务 或 者 数据 查询 而 言 ， 使 用 重复 闹钟 是 一 个 不 错 的 选择 。 它 具 
有 下 列 属性 : 


e WP RA (后 续 章节 中 会 展开 讨论 ) 
。 触发 时 间 。 如 果 触 发 时 间 是 过 去 的 某 个 时 间 点 ， 闪 钟 会 立即 被 触发 ; 


A KE 


e 闹钟 间隔 时 间 。 例 如 ， 一 天 一 次 ， 每 小 时 一 次 ， 每 五 秒 一 次 ， 等 等 ; 
e 在 病 钟 被 触发 时 才 被 发 出 的 Pending Intent。 如 果 你 为 同一 个 Pending Intent 设 置 了 另 一 个 





闹钟 ， 那 么 它 会 将 第 一 个 闹钟 徐 盖 。 


选择 闹钟 类 型 


使 用 重复 闹钟 要 考虑 的 第 一 件 事情 是 闪 钟 的 类 型 。 


病 钟 类 型 有 两 大 类 : ELAPSED REALTIME 和 REAL_TIME_CLOCK (RTC) ° ELAPSED_REALTIME 从 系 
统 启 动 之 后 开始 计算 ， REAL TIME cLock 使 用 的 是 世界 统一 时 间 (UTC) 。 也 就 是 说 由 

于 ELAPSED_REALTIME 不 受 地 区 和 时 区 的 影响 ， 所 以 它 适合 于 基于 时 间 差 的 闹钟 (例如 一 个 每 
过 30 秒 触发 一 次 的 闸 钟 ) 。 REAL TIME cLock 适合 于 那些 依赖 于 地 区 位 置 的 闹钟 。 


两 种 类 型 的 曾 钟 都 还 有 一 个 唤醒 ( wakeup ) 版 本 ， 也 就 是 可 以 在 设备 屏幕 关闭 的 时 候 唤醒 

CPU 。 这 可 以 确保 闹钟 会 在 既定 的 时 间 被 激活 ， 这 对 于 那些 实时 性 要 求 比较 高 的 应 用 (比如 
含有 一 些 对 执行 时 间 有 要 求 的 操作 ) 来 说 非常 有 效 。 如 果 你 没有 使 用 唤醒 版 本 的 闹钟 ， 那 么 
所 有 的 重复 闵 钟 会 在 下 一 次 设备 被 唤醒 时 被 激活 。 


如 果 你 只 是 简单 的 希望 闹钟 在 一 个 特定 的 时 间 间 隔 被 激活 (例如 每 半 小 时 一 次 ) ， 那 么 你 可 
以 使 用 任意 一 种 ELAPSED_REALTIME 类 型 的 闲 钟 ， 通 常 这 会 是 一 个 更 好 的 选择 。 


如 果 你 的 曾 钟 是 在 每 一 天 的 特定 时 间 被 激活 ， 那 么 你 可 以 选择 REAL_TIME_CLOCK 类 型 的 闵 钟 。 
不 过 需要 注意 的 是 ， 这 个 方法 会 有 一 些 缺 陷 一 如果 地 区 发 生 了 变化 ， 应 用 可 能 无 法 做 出 正 
确 的 改变 ; 另外 ， 如 果 用 户 改 变 了 设备 的 时 间 设 置 ， 这 可 能 会 造成 应 用 产生 预期 之 外 的 行 
为 。 使 用 REAL TIME cLock 类 型 的 冰 钟 还 会 有 精度 的 问题 ， 因 此 我 们 建议 你 尽 可 能 使 


用 ELAPSED_REALTIME 类 型 S 
"Ts NW s LARA : 
e ELAPSED REALTIME: 从 设备 启动 之 后 开始 算 起 ， 度 过 了 某 一 段 特定 时 间 后 ， 激 活 
Pending Intent， 但 不 会 唤醒 设备 。 其 中 设备 睡眠 的 时 间 也 会 包含 在 内 。 
e ELAPSED REALTIME WAKEUP : 从 设备 启动 之 后 开始 算 起 ， 度 过 了 某 一 段 特定 时 间 
后 唤醒 设备 。 
e RIC: 在 某 一 个 特定 时 刻 激活 Pending Intent， 但 不 会 唤醒 设备 。 
。 RTC_WAKEUP : 在 某 一 个 特定 时 刻 唤 醒 设备 并 激活 Pending Intent ° 


ELAPSED REALTIME WAKEUP & #1 


下 面 是 使 用 ELAPSED_REALTIME_WAKEUP 的 例子 。 

每 隔 在 30 分 钟 后 唤醒 设备 以 激活 闲 钟 : 
// Hopefully your alarm will have a lower frequency than this! 
alarmMgr.setlInexactRepeating(AlarmManager.ELAPSED REALTIME WAKEUP, 


AlarmManager.INTERVAL HALF HOUR, 
AlarmManager.INTERVAL HALF HOUR, alarmIntent); 


在 一 分 钟 后 唤醒 设备 并 激活 一 个 一 次 性 〈 无 重复 ) NA : 


private AlarmManager alarmMgr; 
private PendingIntent alarmIntent; 


alarmMgr - (AlarmManager)context.getSystemService(Context.ALARM SERVICE); 
Intent intent - new Intent(context, AlarmReceiver.class); 
alarmIntent - PendingIntent.getBroadcast(context, 0, intent, 0); 


alarmMgr.set(AlarmManager.ELAPSED REALTIME WAKEUP, 
SystemClock.elapsedRealtime() + 
60 * 1000, alarmIntent); 


RTC & | 
下 面 是 使 用 RTC_WAKEUP 的 例子 。 


在 大 约 下 午 2 点 唤醒 设备 并 激活 闵 钟 ， 并 不 断 重复 : 


// Set the alarm to start at approximately 2:00 p.m. 
Calendar calendar - Calendar.getInstance(); 
calendar.setTimeInMillis(System.currentTimeMillis()); 
calendar.set(Calendar.HOUR OF DAY, 14); 


// With setInexactRepeating(), you have to use one of the AlarmManager interval 

// constants--in this case, AlarmManager.INTERVAL DAY. 

alarmMgr.setInexactRepeating(AlarmManager.RTC WAKEUP, calendar.getTimeInMillis(), 
AlarmManager.INTERVAL DAY, alarmIntent); 


证 设备 精确 地 在 上 午 8 点 半 被 唤醒 并 激活 闹钟 ， 自 此 之 后 每 20 分 钟 唤醒 一 次 : 


private AlarmManager alarmMgr; 
private PendingIntent alarmIntent; 


alarmMgr - (AlarmManager)context.getSystemService(Context.ALARM SERVICE); 
Intent intent - new Intent(context, AlarmReceiver.class); 
alarmIntent - PendingIntent.getBroadcast(context, 0, intent, 0); 


// Set the alarm to start at 8:30 a.m. 

Calendar calendar = Calendar.getInstance(); 
calendar.setTimeInMillis(System.currentTimeMillis()); 
calendar.set(Calendar.HOUR OF DAY, 8); 
calendar.set(Calendar.MINUTE, 30); 


// setRepeating() lets you specify a precise custom interval--in this case, 

// 20 minutes. 

alarmMgr.setRepeating(AlarmManager.RTC WAKEUP, calendar.getTimeInMillis(), 
1000 * 60 * 20, alarmIntent); 
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ho KATR > Oe ap AY REPO XE 5 REMBEAR SOMA STA 
多 数 应 用 而 言 ， setrnexactRepeating() 会 是 一 个 正确 的 选择 。 当 你 使 用 该 方法 时 ，Android 系 
统 会 集中 多 个 应 用 的 重复 曾 钟 同步 请 求 ， 并 一 起 触发 它们 。 这 样 可 以 减少 电量 的 损耗 。 


对 于 另 一 些 实时 性 要 求 较 高 的 应 用 一 一 例如 ， 闹 钟 需要 精确 地 在 上 午 8 点 半 被 激活 ， 并 且 自 此 
之 后 每 隔 1 小 时 激活 一 次 那么 可 以 使 用 setRepeating() ? 不 过 你 应 该 尽量 避免 使 用 精确 的 
DELE 





使 用 setRepeating() 时 ， 你 可 以 制定 一 个 自 定义 的 时 间 间 隔 ， 但 在 使 

用 setInexactRepeating() 时 不 支持 这 么 做 。 此 时 你 只 能 选择 一 些 时 间 间 隔 常 量 ， 例 

如 :INTERVAL FIFTEEN MINUTES ，INTERVAL _ DAY 等 。 完 整 的 常量 列表 ， 可 以 查 
看 AlarmManager ° 


取消 闹钟 


你 可 能 希望 在 应 用 中 添加 取消 闹钟 的 功能 。 要 取消 闹钟 ， 可 以 调用 AlarmManager 
的 cancel() 方法 ， 并 把 你 不 想 激 活 的 Pendinglntent 传 递 进去 ， 例 如 : 


// If the alarm has been set, cancel it. 
if (alarmMgr!= null) { 
alarmMgr.cancel(alarmIntent); 


} 
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默认 情况 下 ， 所 有 的 闲 钟 会 在 设备 关闭 时 被 取消 。 要 防止 闵 钟 被 取消 ， 你 可 以 让 你 的 应 用 在 
用 户 重 局 设备 后 自动 重启 一 个 重复 闹钟 。 这 样 可 以 让 AlarmManager 继 续 执行 它 的 工作 ， 且 不 
FRAP PAER NG 


具体 步骤 如 下 : 


1. 在 应 用 的 Manifest 文 件 中 设置 RECEIVE_BOOT_CMPLETED 权 限 ， 这 将 允许 你 的 应 用 接收 
系统 启动 完成 后 发 出 的 ACTION BOOT COMPLETED’ J& (只 有 在 用 户 至 少将 你 的 应 用 启 
动 了 一 次 后 ， 这 样 做 才 有 效 ) 


«uses-permission android:name-"android.permission.RECEIVE BOOT COMPLETED"/> 


2. 实 现 BoradcastReceiver 用 于 接收 广播 : 


public class SampleBootReceiver extends BroadcastReceiver { 


@Override 
public void onReceive(Context context, Intent intent) { 
if (intent.getAction().equals("android.intent.action.BOOT_COMPLETED")) { 


// Set the alarm here. 


3. 在 你 的 Manifest 文 件 中 添加 一 个 接收 器 ， 其 Intent-Filter 接 收 ACTION_BOOT_COMPLETED 


这 一 Action : 


«receiver android:name=".SampleBootReceiver" 
android:enabled="false"> 
<intent-filter> 
«action android:name="android.intent.action.BOOT_COMPLETED"></action> 


</intent-filter> 


</receiver> 


注意 Manifest 文 件 中 ， 对 接收 器 设置 了 android:enabled="false" 属性 。 这 意味 着 除非 应 用 显 
式 地 启用 它 ， 不 然 该 接收 器 将 不 被 调用 。 这 可 以 防止 接收 器 被 不 必要 地 调用 。 你 可 以 像 下 面 
这 样 启动 接收 器 (比如 用 户 设置 了 一 个 闹钟 ) 


ComponentName receiver = new ComponentName(context, SampleBootReceiver.class); 
PackageManager pm = context.getPackageManager(); 


pm.setComponentEnabledSetting(receiver, 
PackageManager.COMPONENT ENABLED STATE ENABLED, 
PackageManager.DONT KILL APP); 


一 旦 你 像 上 面 那样 启动 了 接收 器 ， 它 将 一 直 保 持 司 动 状态 ， 即 使 用 户 重启 了 设备 也 不 例外 。 
换 旬 话说， 通过 代码 设置 的 启用 配置 将 会 覆盖 掉 Manifest 文 件 中 的 现 有 配置 ， 即 使 重启 也 不 例 
外 。 接 收 器 将 保持 启动 状态 ， 直 到 你 的 应 用 将 其 禁用 。 你 可 以 像 下 面 这 样 禁用 接收 器 (比如 
用 户 取消 了 一 个 闸 钟 ) 


ComponentName receiver = new ComponentName(context, SampleBootReceiver.class); 
PackageManager pm = context.getPackageManager(); 


pm.setComponentEnabledSetting(receiver, 
PackageManager.COMPONENT ENABLED STATE DISABLED, 
PackageManager.DONT KILL APP); 


制定 重复 定时 的 任务 
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Android' 性 能 优化 


性 能 优化 


编写 :kesenhoo - 原文 :http://developer.android.com/training/best-performance.html 


下 面 的 这 些 课 程 会 介绍 如 何 提升 应 用 的 性 能 ， 如 何 尽 量 减 少 电量 的 消耗 。 
管理 应 用 的 内 存 
如 何 减少 内 存 的 占用 。 
代码 性 能 优化 建议 
如 何 提高 应 用 的 响应 性 与 电池 的 使 用 效率 。 
提升 Layout 的 性 能 
如 何 提升 UI 的 性 能 。 
优化 电池 寿命 
如 何 优化 电量 的 消耗 。 
多 线程 操作 


如 何 通 分 拆 任务 来 提高 程序 性 能 。 


避免 出 现 程序 无 响应 ANR 


如 何 避 免 ANR 。 


JNI 技 巧 


如 何 高 效 的 使 用 JNI。 


SMP Primer for Android 


优化 多 核 处 理 器 架构 下 的 Android 程 序 。 
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Android 性 能 优化 
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管理 应 用 的 内 存 


编写 :kesenhoo - Æ X :http://developer.android.com/training/articles/memory.html 


Random Access Memory(RAM) 在 任何 软件 开发 环境 中 都 是 一 个 很 宝贵 的 资源 。 这 一 点 在 物 
理 内 存 通 常 很 有 限 的 移动 操作 系统 上 ， 显 得 尤为 突出 。 尽 管 Android 的 Dalvik 虚 拟 机 扮演 了 常 
规 的 垃圾 回收 的 角色 ， 但 这 并 不 意味 着 你 可 以 忽视 app 的 内 存 分 配 与 释放 的 时 机 与 地 点 。 


为 了 GC 能 够 从 app 中 及 时 回收 内 存 ， 我 们 需要 注意 避免 内 存 泄露 (通常 由 于 在 全 局 成 员 变量 中 
持 有 对 象 引用 而 导致 ) 并 且 在 适当 的 时 机 (下 面 会 讲 到 的 lifecycle callbacks) 来 释放 引用 对 象 。 
对 于 大 多 数 app 来 说 ，Dalvik 的 GC 会 自动 把 离开 活动 线程 的 对 象 进行 回收 。 


这 篇 文章 会 解释 Android 是 如 何 管理 app 的 进程 与 内 存 分 配 ， 以 及 在 开发 Android 应 用 的 时 候 如 
何 主动 的 减少 内 存 的 使 用 。 关 于 Java 的 资源 管理 机 制 ， 请 参考 其 它 书 籍 或 者 线 上 材料 。 如 果 
你 正在 寻找 如 何 分 析 你 的 内 存 使 用 情况 的 文章 ， 请 参考 这 里 Investigating Your RAM Usage 。 


第 1 部 分 : Android 是 如 何 管理 内 存 的 


Android 并 没有 为 内 存 提 供 交 换 区 (Swap space)， 但 是 它 有 使 用 paging 与 nemory- 
mapping(mmapping) 的 机 制 来 管理 内 存 。 这 意味 着 任何 你 修改 的 内 存 ( 无 论 是 通过 分 配 新 的 对 
象 还 是 去 访问 mmaped pages 中 的 内 容 ) 都 会 贮存 在 RAM 中 ， 而 且 不 能 被 paged out。 因 此 唯一 
完整 释放 内 存 的 方法 是 释放 那些 你 可 能 hold 住 的 对 象 的 引用 ， 当 这 个 对 象 没 有 被 任何 其 他 对 象 
所 引用 的 时 候 ， 它 就 能 够 被 GC 回 收 了 。 只 有 一 种 例外 是 : 如 果 系 统 想 要 在 其 他 地 方 重 用 这 个 
xt Fo 


1) HFA 
Android 通 过 下 面 几 个 方式 在 不 同 的 进程 中 来 实现 共享 RAM: 


e 每 一 个 app 的 进程 都 是 从 一 个 被 叫做 Zygote 的 进程 中 fork 出 来 的 。Zygote 进 程 在 系统 启动 
并 且 载 入 通用 的 ffamework 的 代码 与 资源 之 后 开始 启动 。 为 了 启动 一 个 新 的 程序 进程 ， 系 
统 会 fork Zygote 进 程 生成 一 个 新 的 进程 ， 然 后 在 新 的 进程 中 加 载 并 运行 app 的 代码 。 这 使 
得 大 多 数 的 RAM pages 被 用 来 分 配给 framework 的 代码 ， 同 时 使 得 RAM 资 源 能 够 在 应 用 
的 所 有 进程 中 进行 共享 。 


e 大 多 数 static 的 数据 被 mmapped 到 一 个 进程 中 。 这 不 仅仅 使 得 同样 的 数据 能 够 在 进程 间 进 
行 共 享 ， 而 且 使 得 它 能 够 在 需要 的 时 候 被 paged out。 例 如 下 面 几 种 static 的 数据 : 


o Dalvik 代码 ( 放 在 一 个 预 链接 好 的 .odex 文件 中 以 便 直 接 mapping) 
o App resources (通过 把 资源 表 结 构 设 计 成 便于 mmapping 的 数据 结构 ， 另 外 还 可 以 通 


过 把 APK 中 的 文件 做 aligning 的 操作 来 优化 ) 
o 传统 项 目 元 素 ， 比 如 .so 文件 中 的 本 地 代码 . 

。 在 很 多 情况 下 ，Android 通 过 显 式 的 分 配 共享 内 存 区 域 (例如 ashmem 或 者 gralloc) 来 实现 一 
些 动态 RAM 区 域 能 够 在 不 同 进 程 间 进行 共享 。 例 如 ，window surfaces 在 app 与 screen 
compositor 之 间 使 用 共享 的 内 存 ，cursor buffers 在 content provider 与 client 之 间 使 用 共享 
的 内 存 。 


关于 如 何 查看 app 所 使 用 的 共享 内 存 ， 请 查看 Investigating Your RAM Usage 


2) 分 配 与 回收 内 存 
这 里 有 下 面 几 点 关于 Android 如 何 分 配 与 回收 内 存 的 事实 : 


e 每 一 个 进程 的 Dalvik heap 都 有 一 个 受 限 的 虚拟 内 存 范围 。 这 就 是 逻辑 上 讲 的 heap size * 
它 可 以 随 着 需要 进行 增长 ， 但 是 会 有 一 个 系统 为 它 所 定义 的 上 限 。 

e 逻辑 上 讲 的 heap size 和 实际 物理 上 使 用 的 内 存 数量 是 不 等 的 ，Android 会 计算 一 个 叫做 
Proportional Set Size(PSS) 的 值 ， 它 记录 了 那些 和 其 他 进程 进行 共享 的 内 存 大 小 。( 假 
设 共 享 内 存 大 小 是 10M， 一 共有 20 个 Process 在 共享 使 用 ， 根 据 权 重 ， 可 能 认为 其 中 有 
0.3M 才 能 丨 正 算是 你 的 进程 所 使 用 的 ) 

e Dalvik heap 与 至 上 的 heap size 不 吻合 ， 这 意味 着 Android 并 不 会 去 做 heap 中 的 碎片 整 
理 用 来 关闭 空闲 区 域 。Android 仅 仅 会 在 heap 的 尾 端 出 现 不 使 用 的 空间 时 才 会 做 收缩 逻辑 
heap size 大 小 的 动作 。 但 是 这 并 不 是 意味 着 被 heap 所 使 用 的 物理 内 存 大 小 不 能 被 收缩 。 
在 垃圾 回收 之 后 ，Dalvik 会 遍 历 heap 并 找 出 不 使 用 的 pages ， 然 后 使 用 madvise( 系 统 调 

用 ) 把 那些 pages 返 回 给 kernal。 因 此 ， 成 对 的 allocations 与 deallocations 大 块 的 数据 可 以 
使 得 物理 内 存 能 够 被 正常 的 回收 。 然 而 ， 回 收 雁 片 化 的 内 存 则 会 使 得 效率 低下 很 多 ， 
为 那些 碎片 化 的 分 配 页 面 也 许 会 被 其 他 地 方 所 共享 到 。 


3) 限制 应 用 的 内 存 


为 了 维持 多 任务 的 功能 环境 ，Android 为 每 一 个 app 都 设置 了 一 个 硬性 的 heap size 限 制 。 准 确 
的 heap size 限 制 不 同 设备 的 不 同 RAM 大 小 而 各 有 差异 。 如 果 你 的 app 已 经 到 了 heap 的 
限制 大 小 并 且 再 尝试 分 配 内 存 的 话 ， 会 引起 outofMemoryError 的 错误 。 


在 一 些 情况 下 ， 你 也 许 想 要 查询 当 size 限 制 大 小 是 多 少 ， 然 后 决定 cache 的 大 
小 。 可 以 通过 getMemoryclass() 来 查询 。 这 个 方法 会 返回 一 个 整数 ， 表 明 你 的 应 用 的 heap 
size & 4| X 2 > Mb(megabates) ° 


4) 切换 应 用 


Android 并 不 会 在 用 户 切换 不 同 应 用 时 候 做 交换 内 存 的 操作 。Android 会 把 那些 不 包 
foreground 组 件 的 进程 放 到 LRU cache 中 。 例 如 ， 当 用 户 刚 开始 启动 了 一 个 应 用 ， & icis 
MET PUB dex 5p RJ RASEN o WARHAM o ARSE 


放 到 Cache 中 ， 如 果 用 户 后 来 再 回 到 这 个 应 用 ， 此 进程 就 能 够 被 完整 恢复 ， 从 而 实现 应 用 的 快 
速 切换 。 


如 果 你 的 应 用 中 有 一 个 被 缓存 的 进程 ， 这 个 进程 会 占用 暂时 不 需要 使 用 到 的 内 存 ， 这 个 暂时 
不 需要 使 用 的 进程 ， 它 被 保留 在 内 存 中 ， 这 会 对 系统 的 整体 性 能 有 影响 。 因 此 当 系 统 开 始 进 
入 低 内 存 状 态 时 ， 它 会 由 系统 根据 LRU 的 规则 与 其 他 因素 选择 综合 考虑 之 后 决定 杀 掉 某 些 进 
程 ， 为 了 保持 你 的 进程 能 够 尽 可 能 长 久 的 被 缓存 ， 请 参考 下 面 的 章节 学 习 何 时 释放 你 的 引 
用 。 


对 于 那些 不 在 foreground 的 进程 ，Android 是 如 何 决定 kill 掉 哪 一 类 进程 的 问题 ， 请 参 
Z Processes and Threads. 


第 2 部 分 : 你 的 应 用 该 如 何 管理 内 存 


你 应 该 在 开发 过 程 的 每 一 个 阶段 都 考虑 到 RAM 的 有 限 性 ， 其 至 包括 在 开始 编写 代码 之 前 的 设 
计 阶 段 就 应 该 考虑 到 RAM 的 限制 性 。 我 们 可 以 使 用 多 种 设计 与 实现 方式 ， 他 们 有 着 不 同 的 效 
率 ， 即 使 这 些 方式 只 是 相同 技术 的 不 断 组 合 与 演变 。 


为 了 使 得 你 的 应 用 性 能 效率 更 高 ， 你 应 该 在 设计 与 实现 代码 时 ， 遵 循 下 面 的 技术 要 点 。 


1) 珍惜 Services 资 源 


如 果 你 的 应 用 需要 在 后 台 使 用 service， 除 非 它 被 触发 并 执行 一 个 任务 ， 否 则 其 他 时 候 service 
都 应 该 是 停止 状态 。 另 外 需要 注意 当 这 个 service 完 成 任务 之 后 因为 停止 service 失 败 而 引起 的 
内 存 泄 漏 。 


"d 动 一 个 service， 系 统 会 倾向 为 了 保留 这 个 service 而 一 直 保 留 service 所 在 的 进程 。 这 使 

进程 的 运行 代价 很 高 ， 因 为 系统 没有 办 法 把 service 所 占用 的 RAM 空 间 腾 出 来 让 给 其 他 组 
e 另外 service 还 不 能 被 paged out。 这 减少 了 系统 能 够 存放 到 LRU 缓 存 当 中 的 进程 数量 ， 它 
会 影响 app 之 间 的 切换 效率 。 它 甚至 会 导致 系统 内 存 使 用 不 稳定 ， 从 而 无 法 继续 保持 住所 有 目 
前 正在 运行 的 Service。 


你 的 service 的 最 好 办 法 是 使 用 IntentService ， 它 会 在 处 理 完 交代 给 它 的 intent 任 务 之 后 尽 
结束 自己 。 更 多 信息 ， 请 阅读 Running in a Background Service. 

当 一 个 Service 已 经 不 再 需要 的 时 候 还 继续 保留 它 ， 这 对 Android 应 用 的 内 存 管理 来 说 是 最 糟糕 

的 错误 之 一 。 因 此 千 万 不 要 贪 禁 的 使 得 一 个 Service 持 续 保 留 。 不 仅仅 是 因为 它 会 使 得 你 的 应 


用 因为 RAM 空 间 的 不 足 而 性 能 糟糕 ， 还 会 使 得 用 户 发 现 那些 有 着 常 驻 后 台 行 为 的 应 用 并 且 可 
fie Sp RE 


2) 当 UI 隐 藏 时 释放 内 存 


当 用 户 切 换 到 其 它 应 用 并 且 你 的 应 用 UI 不 再 可 见 时 ， 你 应 该 释放 你 的 应 用 UI 上 所 占用 的 所 有 
内 存 资源 。 在 这 个 时 候 释放 UI 资 源 可 以 显著 的 增加 系统 缓存 进程 的 能 力 ， 它 会 对 用 户 体验 有 
着 很 直接 的 影响 。 


为 了 能 够 接收 到 用 户 离 开 你 的 UI 时 的 通知 ， 你 需要 实现 Activtiy 类 里 面 的 onTrimMemory() 回调 
方法 。 你 应 该 使 用 这 个 方法 来 监听 到 TRIM MEMORY UI HIDDEN 级 别 的 回调 ， 此 时 意味 着 你 的 UI 
已 经 隐藏 ， 你 应 该 释放 那些 仅仅 被 你 的 UUI 使 用 的 资源 。 


请 注意 : 你 的 应 用 仅仅 会 在 所 有 UI 组 件 的 被 隐藏 的 时 候 接 收 到 onTrimMemory() 的 回调 并 带 有 
参数 TRIM_MEMORY_UI_HIDDEN 。 这 与 onStop() 的 回调 是 不 同 的 ，onStop 会 在 activity 的 实例 隐藏 
时 会 执行 ， 例 如 当 用 户 从 你 的 app 的 某 个 activity 跳 转 到 另外 一 个 activity 时 前 面 activity 的 
onStop() 会 被 执行 。 因 此 你 应 该 实现 onStop 回 调 ， 并 且 在 此 回调 里 面 释放 activity 的 资源 ， 例 
如 释放 网 络 连接 ， 注 销 监听 广播 接收 者 。 除 非 接 收 
$lonTrimMemory(TRIM MEMORY _UI_HIDDEN)) 的 回调 ， 和 否 者 你 不 应 该 释放 你 的 UI 资 源 。 
这 确保 了 用 户 从 其 他 activity 切 回来 时 ， 你 的 UI 资源 仍然 可 用 ， 并 且 可 以 迅速 恢复 activity 。 


3) 当 内 存 紧 张 时 释放 部 分 内 存 


在 你 的 app 生 命 周期 的 任何 阶段 ，onTrimMemory 的 回调 方法 同样 可 以 告诉 你 整个 设备 的 内 存 
资源 已 经 开始 紧张 。 你 应 该 根据 onTrimMemory 回 调 中 的 内 存 级 别 来 进一步 决定 释放 哪些 资 


e TRIM MEMORY RUNNING MODERATE : 你 的 app 正 在 运行 并 且 不 会 被 列 为 可 杀 死 
的 。 但 是 设备 此 时 正 运行 于 低 内 存 状态 下 ， 系 统 开 始 触发 杀 死 LRU Cache 中 的 Process 的 
Aus] © 

e TRIM MEMORY RUNNING LOW : 你 的 app 正 在 运行 且 没有 被 列 为 可 杀 死 的 。 但 是 设 
备 正 运行 于 更 低 内 存 的 状态 下 ， 你 应 该 释放 不 用 的 资源 用 来 提升 系统 性 能 〈 但 是 这 也 会 
直接 影响 到 你 的 app 的 性 能 ) 。 

e TRIM MEMORY RUNNING CRITICAL : 你 的 app 仍 在 运行 ， 但 是 系统 已 经 把 LRU 
Cache 中 的 大 多 数 进 程 都 已 经 杀 死 ， 因 此 你 应 该 立即 释放 所 有 非 必 须 的 资源 。 如 果 系 统 不 
能 回收 到 足够 的 RAM 数 量 ， 系 统 将 会 清除 所 有 的 LRU 缓 存 中 的 进程 ， 并 且 开 始 杀 死 那些 
之 前 被 认为 不 应 该 杀 死 的 进程 ， 例 如 那个 包含 了 一 个 运行 态 Service 的 进程 。 


同样 ， 当 你 的 app 进 程 正在 被 cached 时 ， 你 可 能 会 接受 到 从 onTrimMemory() 中 返回 的 下 面 的 
值 之 一 : 


e TRIM MEMORY BACKGROUND: 系统 正 运行 于 低 内 存 状态 并 且 你 的 进程 正 处 于 LRU 绥 
存 名 单 中 最 不 容易 杀 掉 的 位 置 。 尽 管 你 的 app 进 程 并 不 是 处 于 被 杀 掉 的 高 危险 状态 ， 系 统 
可 能 已 经 开始 杀 掉 LRU 缓 存 中 的 其 他 进程 了 。 你 应 该 释放 那些 容易 恢复 的 资源 ， 以 便于 
你 的 进程 可 以 保留 下 来 ， 这 样 当 用 户 回 退 到 你 的 app 的 时 候 才 能 够 迅速 恢复 。 

e TRIM MEMORY MODERATE: 系统 正 运行 于 低 内 存 状 态 并 且 你 的 进程 已 经 已 经 接近 
LRU 名 单 的 中 部 位 置 。 如 果 系 统 开始 变 得 更 加 内 存 紧张 ， 你 的 进程 是 有 可 能 被 杀 死 的 。 

e TRIM MEMORY COMPLETE: 系统 正 运 行 与 低 内 存 的 状态 并 且 你 的 进程 正 处 于 LRU 名 


单 中 最 容易 被 杀 掉 的 位 置 。 你 应 该 释放 任何 不 影响 你 的 app 恢 复 状态 的 资源 。 


因为 onTrimMemory() 的 回调 是 在 API 14 才 被 加 进来 的 ， 对 于 老 的 版 本 ， 你 可 以 使 
用 onLowIMemory) 回 调 来 进行 兼容 。onLowMemory 相 当 与 TRIM_MEMORY_COMPLETE ° 


Note: 当 系 统 开 始 清除 LRU 缓 存 中 的 进程 时 ， 尽 管 它 首先 按照 LRU 的 顺序 来 操作 ， 
它 同 样 会 考虑 进 RE 。 因 此 消耗 越 少 的 进程 则 越 容易 被 留 下 来 。 


4) 检查 你 应 该 使 用 多 少 的 内 存 


正如 前 面 提 到 的 ， 每 一 个 Android 设 备 都 会 有 不 同 的 RAM 总 大 小 与 可 用 空间 ， 因 此 不 同 设备 为 
app 提 供 了 不 同 大 小 的 heap 限 制 。 你 可 以 通过 调用 getMemoryClass()) 来 获取 你 的 app 的 可 用 
heap X. 。 如 果 你 的 app 尝 试 申请 更 多 的 内 存 ， 会 出 现 OutOfMemory 的 错误 。 


在 一 些 特殊 的 情景 下 ， flde cansa ppm SR largeHeap-true 的 属性 
来 声明 一 个 更 大 的 heap 空 间 。 如 果 你 这 样 做 ， 你 可 以 通过 getLargeMemoryClass()) 来 获取 到 
一 个 更 大 的 heap size ° 


然而 ， 能 够 获取 更 大 heap 的 设计 本 意 是 为 了 一 小 部 分 会 消耗 大 量 RAM 的 应 用 (例如 一 个 大 图 片 
niis 用 )。 不 要 轻易 的 因为 你 需要 使 用 大 量 的 内 存 而 去 请 求 一 个 大 的 heap size » RA X tk 
清楚 的 知道 哪里 会 使 用 大 量 的 内 存 并 且 为 什么 这 些 内 存 必 须 被 保留 时 才 去 使 用 large heap. Al 
hock 少 使 用 large heap。 使 用 额外 的 内 存 GA Me MR 并 且 会 使 得 GC 的 

每 次 运行 时 间 更 长 。 在 任务 切换 时 ， 系 统 的 性 能 会 变 得 大 打折 扣 。 


另外 , large heap 并 不 一 定 能 够 获取 到 更 大 的 heap。 在 某 些 有 严格 限制 icon ' large heap 
的 大 小 和 通常 的 heap size 是 一 样 的 。 因 此 即使 你 申请 了 large heap， 你 还 是 应 该 通过 执行 
getMemoryClass() 来 检查 实际 获取 到 的 heap 大 小 。 


5) 避免 pitmaps 的 浪费 


当 你 加 载 一 个 bitmap 时 ， 仅 仅 需要 保留 适 配 当 前 屏幕 设备 分 辩 率 的 数据 即 可 ， 如 果 原 图 高 于 
你 的 设备 分 辨认 ， 需 要 做 缩小 的 动作 。 请 记 住 ， 增 加 bitmap 的 尺寸 会 对 内 存 呈 现 出 2 次 方 的 增 
加 ， 因 为 X 与 Y 都 在 增加 。 


Note: 在 Android 2.3.x (API level 10) 及 其 以 下 , bitmap 对 象 的 pixel data 是 存放 在 native 内 
存 中 的 ， 它 不 便于 调试 。 然 而 ， 从 Android 3.0(API level 11) 开 始 ，bitmap pixel data 是 分 
Mn 的 app 的 Dalvik heap t , 这 提升 了 GC 的 工作 效率 并 且 更 加 容易 Debug。 因 BOE 

你 的 app 使 用 bitmap 并 在 昌 的 机 器 上 引发 了 一 些 内 存 问 题 ， 切 换 到 3.0 以 上 的 机 器 上 进行 
Debug ° 


6) 使 用 优化 的 数据 容器 


利用 Android Framework 里 面 优化 过 的 容器 类 ， 例 如 SparseArray, SparseBooleanArray, 5 
LongSparseArray。 通常 的 HashMap 的 实现 方式 更 加 消耗 内 存 ， 因 为 它 需 要 一 个 额外 的 实例 
对 象 来 记录 Mapping 操 作 。 另 外 ，SparseArray 更 加 高 效 在 于 他 们 避免 了 对 key 与 value 的 
autobox 自 动 装 箱 ， 并 且 避 免 了 装 箱 后 的 解 箱 。 


7) 请 注意 内 存 开销 


对 你 所 使 用 的 语言 与 库 的 成 本 与 开销 有 所 了 解 ， 从 开始 到 结束 ， 在 设计 你 的 app 时 谨 记 这 些 信 
息 。 通 常 ， 表 面 上 看 起 来 无 关 痛 痒 (innocuous) 的 事情 也 许 实际 上 会 导致 大 量 的 开销 。 例 如 


e Enums 的 内 存 消 耗 通常 是 static constants 的 2 倍 。 你 应 该 尽量 避免 在 Android 上 使 用 
enums ° 

。 在 Java 中 的 每 一 个 类 (包括 匿名 内 部 类 ) 都 会 使 用 大 概 500 bytes ^ 

。 每 一 个 类 的 实例 花 销 是 12-16 bytes。 

e 往 HashMap 添 加 一 个 entry 需 要 额 一 个 额外 占用 的 32 bytes 的 entry 对 象 。 


8) 请 注意 代码 “抽象 ” 


通常 ， 开 发 者 使 用 抽象 作为 "好 的 编程 实践 "， 因 为 抽象 能 够 提升 代码 的 灵活 性 与 可 维护 性 。 然 
而 ， 抽 象 会 导致 一 个 显著 的 开销 : 通常 他 们 需要 同等 量 的 代码 用 于 可 执行 。 那 些 代码 会 被 
map 到 内 存 中 。 因 此 如 果 你 的 抽象 没有 显著 的 提升 效率 ， 应 该 尽量 避免 他 们 。 


9) 为 序列 化 的 数据 使 用 nano protobufs 


Protocol buffers 是 由 Google 为 序列 化 结构 数据 而 设计 的 ， 一 种 语言 无 关 ， 平 台 无 关 ， 具 有 良 
好 扩展 性 的 协议 。 类 似 XML， 却 比 XML 更 加 轻 量 ， 快 速 ， NR 。 如 果 你 需要 为 你 的 数据 实现 
协议 化 ， is 该 在 客户 端的 代码 中 总 是 使 用 nano protobufs。 通 常 的 协议 化 操作 会 生成 大 量 繁 
琐 的 代码 ， 这 容易 给 你 的 app 带 来 许多 问题 : 增加 RAM 的 使 用 量 ， 显 著 增 加 APK 的 大 小 ， 更 慢 
Re， 更 容易 达到 DEX 的 字符 限制 。 


ik 
关于 更 多 细节 ， 请 参考 protobuf readme 的 "Nano version" € ¥ o 
10) 避免 使 用 依赖 注入 框架 


使 用 类 似 Guice 或 者 RoboGuice 等 famework injection 包 是 很 有 效 的 ， 因 为 他 们 能 够 简化 你 的 
代码 。 


Notes : RoboGuice 2 通过 依赖 注入 改变 代码 风格 ， 让 Android 开 发 时 的 体验 更 好 。 你 在 
调用 getIntent().getExtras() 时 经 常 忘记 检查 null % ? RoboGuice 2 可 以 帮 你 做 。 你 
认为 将 findviewById() 的 返回 值 强制 转换 成 TextView 是 本 不 必要 的 工作 吗 ? 
RoboGuice 2 可 以 帮 你 。RoboGuice 把 这 些 需 要 猜测 性 的 工作 移 到 Android 开 发 以 外 去 

^ RoboGuice 2 会 负责 注入 你 的 View, Resource, System Service 或 者 其 他 对 象 等 等 类 
的 细节 。 


然而 ， 那 些 框架 会 通过 扫描 你 的 代码 执行 许多 初始 化 的 操作 ， 这 会 导致 你 的 代码 需要 大 量 的 
RAM 来 mapping 人 代码， 而 且 mapped pages 会 长 时 间 的 被 保留 在 RAM 中 。 


11) È %14 A $ =F libraries 


很 多 开源 的 library 代 码 都 不 是 为 移动 网 络 环境 而 编写 的 ， 如 果 运 用 在 移动 设备 上 ，， 这 样 的 效 
率 并 不 高 。 当 你 决定 使 用 一 个 第 三 方 library 的 时 候 ， 你 应 该 针对 移动 网 络 做 繁琐 的 迁移 与 维护 
的 工作 。 


即使 是 针对 Android 而 设计 的 library， 也 可 能 是 很 危险 的 ， 因 为 每 一 个 library 所 做 的 事情 都 是 不 
一 样 的 。 例 如 ， 其 中 一 个 lib 使 用 的 是 nano protobufs, 而 另外 一 个 使 用 的 是 micro protobufs。 
那么 这 样 ， 在 你 thapp 2. 3-4 24eprotobufil 实现 方式 。 这 样 的 冲突 同样 可 能 发 生 在 输出 日 
志 ， 加 载 图 片 ， 缓 存 等 等 模块 里 面 。 


同样 不 要 陷入 为 了 1 个 或 者 2 个 功能 而 导入 整个 library 的 陷阱 。 如 果 没 有 一 个 合适 的 库 与 你 的 需 
求 相 吻合 ， 你 应 该 考虑 自己 去 实现 ， 而 不 是 导入 一 个 大 而 全 的 解决 方案 。 
12) 优化 整体 性 能 


官方 有 列 出 许多 优化 整个 app 性 能 的 文章 : Best Practices for Performance。 这 篇 文章 就 是 其 
中 之 一 。 有 些 文 章 是 讲解 如 何 优 化 app 的 CPU 使 用 效率 ， 有 些 是 如 何 优 化 app 的 内 存 使 用 效 
Zo 


zx 


尔 还 应 该 阅读 optimizing your UI| 来 为 layout 进 行 优化 。 同 样 还 应 该 关注 lint 工 具 所 提出 的 建 
议 ， 进 行 优化 。 


13) 使 用 ProGuard 来 别 除 不 需要 的 代码 


ProGuard 能 够 通过 移 除 不 需要 的 代码 ， 重 命名 类 ， 域 与 方法 等 方 对 代码 进行 压缩 ， 优 化 与 混 
淆 。 使 用 ProGuard 可 以 使 得 你 的 代码 更 加 紧凑 ， 这 样 能 够 使 用 更 少 mapped 代 码 所 需要 的 
RAM ° 


14) 对 最 终 的 APK 使 用 zipalign 


在 编写 完 所 有 代码 ， 并 通过 编译 系统 生成 APK 之 后 ， 你 需要 使 用 zipalign 对 APK 进 行 重新 校 
准 。 如 果 你 不 做 这 个 步骤 ， 会 导致 你 的 APK 需 要 更 多 的 RAM ， 因 为 一 些 类 似 图 片 资源 的 东西 
不 能 被 mapped ° 


Notes: Google Play 不 接受 没有 经 过 zipalign 的 APK ° 


15) 分 析 你 的 RAM 使 用 情况 


一 旦 你 获取 到 一 个 相对 稳定 的 版 本 后 ， 需 要 分 析 你 的 app 整 个 生命 周期 内 使 用 的 内 存 情 况 ， 并 
进行 优化 ， 更 多 细节 请 参考 Investigating Your RAM Usage. 


16) 使 用 多 进程 


如 果 合 适 的 话 ， 有 一 个 更 高 POEA TAT ENA E 过 把 你 的 app 组 件 切 
分 成 多 个 组 件 ， 运 行 在 不 同 的 进程 中 。 这 个 技术 必须 说 惯 使 用 ， ac 该 运行 在 多 
个 进程 中 。 因 为 如 果 使 用 不 当 ， 它 会 显著 增加 内 存 的 使 用 ， 而 不 是 减少 。 当 你 的 app 需 要 在 后 
台 运 行 与 前 台 一 样 的 大 量 的 任务 的 时 候 ， 可 以 考虑 使 用 这 个 技术 。 


一 个 典型 的 例子 是 创建 一 个 可 以 长 时 间 后 台 播 放 的 Music Player。 如 果 整 个 app 运 行 在 一 个 进 
程 中 ， 当 后 台 播放 的 时 候 ， 前 台 的 那些 UI 资 源 也 没有 办 法 得 到 释放 。 类 似 这 样 的 app 可 以 切 分 
成 2 个 进程 : 一 个 用 来 操作 UI， 另 外 一 个 用 来 后 台 的 Service. 


你 可 以 通过 在 manifest 文 件 中 声明 'android:process' 属 性 来 实现 某 个 组 件 运行 在 另外 一 个 进程 
的 操作 。 


«service android:name=".PlaybackService" 
android:process-":background" /> 


更 多 关于 使 用 这 个 技术 的 细节 ， 请 参考 原文 ， 链 接 如 下 。 
http://developer.android.com/training/articles/memory.html 


代码 性 能 优化 建议 


编写 :kesenhoo - 原文 :http://developer.android.com/training/articles/perf-tips.html 


这 篇 文章 主要 介绍 一 些小 细节 的 优化 技巧 ， 虽 然 这 些小 技巧 不 能 较 大 幅度 的 提升 应 用 性 能 ， 
但 是 恰当 的 运用 这 些小 技巧 并 发 生 累积 效应 的 时 候 ， 对 于 整个 App 的 性 能 提升 还 是 有 不 小 作用 
的 。 通 常 来 说 ， 选 择 合适 的 算法 与 数据 结构 会 是 你 首要 考虑 的 因素 ， 在 这 篇 文章 中 不 会 涉及 
这 方面 的 知识 点 。 你 应 该 使 用 这 篇 文章 中 的 小 技巧 作为 平时 写 代 码 的 习惯 ， 这 样 能 够 提升 代 
码 的 效率 。 


通常 来 说 ， 高 效 的 代码 需要 满足 下 面 两 个 原则 : 


e 不 要 做 宛 余 的 工作 
e 尽量 避免 执行 过 多 的 内 存 分 配 操作 


在 优化 App 时 其 中 一 个 难点 就 是 让 App 能 在 各 种 型 号 的 设备 上 运行 。 不 同 版 本 的 虚拟 机 在 不 同 
的 处 理 器 上 会 有 不 同 的 运行 速度 。 你 其 至 不 能 简单 的 认为 “设备 X 的 速度 是 设备 Y 的 F 倍 "”， 然 后 
还 用 这 种 倍数 关系 去 推测 其 他 设备 。 另 外 ， 在 模拟 器 上 的 运行 速度 和 在 实际 设备 上 的 速度 没 
有 半点 关系 。 同 样 ， 设 备 有 没有 JIT 也 对 运行 速度 有 重大 影响 : 在 有 JIT 情 况 下 的 最 优化 代码 不 
一 定 在 没有 JIT 的 情况 下 也 是 最 优 的 。 


为 了 确保 App 在 各 设备 上 都 能 良好 运行 ， 就 要 确保 你 的 代码 在 不 同 档次 的 设备 上 都 尽 可 能 的 优 
化 。 


避免 创建 不 必要 的 对 象 


创建 对 象 从 来 不 是 免费 的 。Generational GC 可 以 使 临时 对 象 的 分 配 变 得 廉价 一 些 ， 但 是 执行 
分 配 内 存 总 是 比 不 执行 分 配 操作 更 部 贵 。 


随 着 你 在 App 中 分 配 更 多 的 对 象 ， 你 可 能 需要 强制 gc， 而 gc 操作 会 给 用 户 体验 带 来 一 点 点 卡 
Wi» 3 RI. Android 2.3 开 始 ， 引 入 了 并 发 gc， 它 可 以 帮助 你 显著 提升 gc 的 效率 ， 减 轻卡 顿 ， 
但 毕竟 不 必要 的 内 存 分 配 操作 还 是 应 该 尽量 避免 。 


因此 请 尽量 避免 创建 不 必要 的 对 象 ， 有 下 面 一 些 例子 来 说 明 这 个 问题 : 


e 如 果 你 需要 返回 一 个 String 对 象 i 并 且 你 知道 它 最 终 会 需要 连接 到 一 个 StringBuffer ^? 请 
修改 你 的 函数 实现 方式 ， 训 免 直接 进行 连接 操作 ， 应 该 采用 创建 一 个 临时 对 象 来 做 字符 
串 的 拼接 这 个 操作 。 

e 当 从 已 经 存在 的 数据 集中 抽取 出 String 的 时 候 ， 尝 试 返回 原 数 据 的 Substring 对 象 ， 而 不 是 
创建 一 个 重复 的 对 象 。 使 用 substring 的 方式 ， 你 将 会 得 到 一 个 新 的 String 对 象 ， 但 是 这 个 
string 对 象 是 和 原 string 共 享 内 部 char[] 空间 的 。 


一 个 稍微 激进 点 的 做 法 是 把 所 有 多 维 的 数据 分 解 成 一 维 的 数组 : 


e 一 组 int 数 据 要 比 一 组 Integer 对 象 要 好 很 多 。 可 以 得 知 ， 两 组 一 维 数组 要 比 一 个 二 维 数组 
更 加 的 有 效率 。 同 样 的 ， 这 个 道理 可 以 推广 至 其 他 原始 数据 类 型 。 

e 如 果 你 需要 实现 一 个 数组 用 来 存放 (Foo,Bar) 的 对 象 ， 记 住 使 用 Foo[] 与 Bar[] 要 比 (Foo,Bar) 
好 很 多 。( 例 外 的 是 ， 为 了 某 些 好 的 API 的 设计 ， 可 以 适当 做 一 些 妥 协 。 但 是 在 自己 的 代 
码 内 部 ， 你 应 该 多 多 使 用 分 解 后 的 容易 ) 。 


通常 来 说 ， 需 要 避免 创建 更 多 的 临时 对 象 。 更 少 的 对 象 意味 者 更 少 的 gc 动作 ，gc 会 对 用 户 体 
验 有 比较 直接 的 影响 。 


选择 Static 而 不 是 Virtual 


如 果 你 不 需要 访问 一 个 对 象 的 值 ， 请 保证 这 个 方法 是 static 类 型 的 ， 这 样 方法 调用 将 快 
15%-20%。 这 是 一 个 好 的 习惯 ， 因 为 你 可 以 从 方法 声明 中 得 知 调用 无 法 改变 这 个 对 象 的 状 


常量 声明 为 Static Final 
考虑 下 面 这 种 声明 的 方式 


static int intVal = 42; 
static String strVal - "Hello, world!"; 


编译 器 会 使 用 一 个 初始 化 类 的 函数 ， 然 后 当 类 第 一 次 被 使 用 的 时 候 执行 。 这 个 函数 将 42 存 
入 intval ， 还 从 class 文 件 的 常量 表 中 提取 了 strval 的 引用 。 当 之 后 使 
用 intval 或 strval 的 时 候 ， 他 们 会 直接 被 查询 到 。 


我 们 可 以 用 final 关键 字 来 优化 : 


static final int intVal - 42; 
static final String strVal - "Hello, world!"; 


这 时 再 也 不 需要 上 面 的 方法 了 ， 因 为 final 声明 的 常量 进入 了 静态 dex 文 件 的 域 初始 化 部 分 。 调 
用 intval 的 代码 会 直接 使 用 42， 调 用 strval 的 代码 也 会 使 用 一 个 相对 廉价 的 “字符 串 常 
量 " 指 令 ， 而 不 是 查 表 。 


Notes : 这 个 优化 方法 只 对 原始 类 型 和 String 类 型 有 效 ， 而 不 是 任意 引用 类 型 。 不 过 ， 在 
必要 时 使 用 static final 是 个 很 好 的 习惯 。 


避免 内 部 的 Getters/Setters 


像 C++ 等 native language， 通 常 使 用 getters(i = getCount()) 而 不 是 直接 访问 变量 (i = 
mCount)。 这 是 编写 C++ 的 一 种 优秀 习惯 ， 而 且 通 常 也 被 其 他 面向 对 象 的 语言 所 采用 ， 例 如 
C# 与 Java， 因 为 编译 器 通常 会 做 inline 访 问 ， 而 且 你 需要 限制 或 者 调试 变量 ， 你 可 以 在 任何 时 
候 在 getter/setter 里 面 添加 代码 。 


然而 ， 在 Android 上 ， 这 不 是 一 个 好 的 写法 。 庶 函数 的 调用 比 起 直接 访问 变量 要 耗费 更 多 。 在 
面向 对 象 编程 中 ， 将 getter 和 setting 暴 露 给 公用 接口 是 合理 的 ， 但 在 类 内 部 应 该 仅仅 使 用 域 直 
接 访 问 。 

在 没有 JIT(Just In Time Compiler) 时 ， 直 接 访 问 变量 的 速度 是 调用 getter 的 3 倍 。 有 JIT 时 ， 直 
接 访问 变量 的 速度 是 通过 getter 访 问 的 7 倍 。 

请 注意 ， 如 果 你 使 用 ProGuard， 你 可 以 获得 同样 的 效果 ， 因 为 ProGuard 可 以 为 你 inline 
accessors. 


使 用 增强 的 For 循 环 


增强 的 For 循 环 (也 被 称 为 for-each 循环 ) 可 以 被 用 在 实现 了 Iterable 接口 的 collections 以 及 
数组 上 。 使 用 collection 的 时 候 ，lterator 会 被 分 配 ， 用 于 for-each 调 用 hasNext() 和 next() 方 
法 。 使 用 ArrayList 时 ， 手 写 的 计数 式 for 循 环 会 快 3 倍 (不管 有 没有 JIT) ， 但 是 对 于 其 他 
collection， 增 强 的 for-each 循 环 写法 会 和 和 迭代 器 写法 的 效率 一 样 。 


请 比较 下 面 三 种 循环 的 方法 : 


static class Foo { 
int mSplat; 
} 


Foo[] mArray = ... 


public void zero() { 
int sum - 0; 
for (int i = 0; i « mArray.length; ++i) { 
sum += mArray[i].mSplat; 
} 
} 


public void one() { 
int sum - 0; 
Foo[] localArray - mArray; 
int len - localArray.length; 


for (int i = 0; i « len; ++1) { 
sum += localArray[i].mSplat; 
} 
} 


public void two() { 
int sum - 0; 
for (Foo a : mArray) { 
sum += a.mSplat; 


} 


e Zero() 是 最 慢 的 ， 因 为 JIT 没 有 办 法 对 它 进 行 优化 。 

© one() 稍 微 快 些 。 

e two() 在 没有 做 JIT 时 是 最 快 的 ， 可 是 如 果 经 过 JIT 之 后 ， 与 方法 one() 是 差不多 一 样 快 的 。 
它 使 用 了 增强 的 循环 方法 for-each 。 


所 以 请 尽量 使 用 for-each 的 方法 ， 但 是 对 于 ArrayList， 请 使 用 方法 one()。 


Tips : 你 还 可 以 参考 Josh Bloch 的 Effective Java》 这 本 书 的 第 46 条 


使 用 包 级 访问 而 不 是 内 部 类 的 私有 访问 


参考 下 面 一 段 代码 


public class Foo { 
private class Inner { 
void stuff() { 
Foo.this.doStuff(Foo.this.mValue); 
} 
} 


private int mValue; 


public void run() { 
Inner in - new Inner(); 
mValue = 27; 
in.stuff(); 


} 


private void doStuff(int value) { 
System.out.println("Value is " + value); 


} 


这 里 重要 的 是 ， 我 们 定义 了 一 个 私有 的 内 部 类 ( Foo$Inner ) ， 它 直接 访问 了 外 部 类 中 的 私 
有 方法 以 及 私有 成 员 对 象 。 这 是 合法 的 ， 这 上段 代码 也 会 如 同 预 期 一 样 打印 出 "Value is 27" ° 


问题 是 ，VM 因 为 Foo 和 Foo$Inner 是 不 同 的 类 ， 会 认为 在 Foo$Inner 中 直接 访问 Foo 类 的 私 
有 成 员 是 不 合法 的 。 即 使 Java 语 言 允 许 内 部 类 访问 外 部 类 的 私有 成 员 。 为 了 去 除 这 种 差异 ， 
编译 器 会 产生 一 些 仿造 函数 : 


/*package*/ static int Foo.access$100(Foo foo) { 
return foo.mValue; 


} 
/*package*/ static void Foo.access$200(Foo foo, int value) { 
foo.doStuff(value); 


} 


每 当 内 部 类 需要 访问 外 部 类 中 的 mValue 成 员 或 需要 调用 doStuff0 函 数 时 ， 它 都 会 调用 
态 方法 。 这 意味 着 ， 上 面 的 代码 可 以 归结 为 ， 通 过 accessor 有 函数 来 访问 成 员 变量 。 odi 

我 们 说 过 ， 通 过 accessor 会 比 直接 访问 域 要 慢 。 所 以 ， 这 是 一 个 特定 语言 用 Eu 

的 例子 


如 果 你 正在 性 能 热 区 〈hotspot: 高 频率 、 重 复 执行 的 代码 段 ) 使 用 像 这 样 的 代码 ， 你 可 以 把 内 
问 的 域 和 方法 声明 为 包 级 访问 ， 而 不 是 私有 访问 权限 。 不 幸 的 是 ， 这 意味 着 在 相 
包 中 的 其 他 类 也 可 以 直接 访问 这 些 域 ， 所 以 在 公开 的 API 中 你 不 能 这 样 做 。 


避免 使 用 float 类 型 


Android 系 统 中 float 类 型 的 数据 存 取 速度 是 int 类 型 的 一 半 ， 尽 量 优先 采用 int 类 型 。 


就 速度 而 言 ， 现 代 硬 件 上 ，float 和 double 的 速度 是 一 样 的 。 空 间 而 言 ，double 是 两 倍 float 的 
大 小 。 在 空间 不 是 问题 的 情况 下 ， 你 应 该 使 用 double 。 


同样 ， 对 于 整 型 ， 有 些 处 理 器 实现 了 硬件 几 倍 的 乘法 ， 但 是 没有 除法 。 这 时 ， 整 型 的 除法 和 
取 余 是 在 软件 内 部 实现 的 ， 这 在 你 使 用 哈 希 表 或 大 量 计 算 操 作 时 要 考虑 到 。 


使 用 库 函 数 


除了 那些 常见 的 让 你 多 使 用 自 带 库 函 数 的 理由 以 外 ， 记 得 系统 函数 有 时 可 以 替代 第 三 方 库 ， 
并 且 还 有 汇编 级 别 的 优化 ， 他 们 通常 比 带 有 JIT 的 Java 编 译 出 来 的 代码 更 高 效 。 典 型 的 例子 
是 : Android API 中 的 string.indexof() ，Dalvik 出 于 内 联 性 能 考虑 将 其 替换 。 同 样 
System.arraycopy() 函数 也 被 替换 > 这样 的 性 能 在 Nexus One 测 试 ， 比 手写 的 for 循 环 并 使 用 
JIT 还 快 9 倍 。 


Tips : 参见 Josh Bloch 的 《Effective Java》 这 本 书 的 第 47 条 
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结合 Android NDK 使 用 native 代 码 开发 ， 并 不 总 是 比 Java 直 接 开 发 的 效率 更 好 的 。Java 转 
native 代 码 是 有 代价 的 ， 而 且 JIT 不 能 在 这 种 情况 下 做 优化 。 如 果 你 在 native 代 码 中 分 配 资源 
(比如 native 堆 上 的 内 存 ， 文 件 描 述 符 等 等 ) ， 这 会 对 收集 这 些 资源 造成 巨大 的 困难 。 你 同时 
也 需要 为 各 种 架构 重新 编译 代码 (而 不 是 依赖 JIT) 。 你 甚至 对 已 同样 架构 的 设备 都 需要 编译 
多 个 版 本 : 为 G1 的 ARM 架 构 编 译 的 版 本 不 能 完全 使 用 Nexus One 上 ARM 架 构 的 优势 ， 反 之 亦 
IR o 


Native 代码 是 在 你 已 经 有 本 地 代码 ， 想 把 它 移植 到 Android 平 台 时 有 优势 ， 而 不 是 为 了 优化 已 
有 的 Android Java 代 码 使 用 。 


如 果 你 要 使 用 JNI, 请 学 习 JNI Tips 


Tips : 参见 Josh Bloch 的 《Effective Java》 这 本 书 的 第 54 条 


关于 性 能 的 误区 


在 没有 JIT 的 设备 上 ， 使 用 一 种 确切 的 数据 类 型 确实 要 比 抽 象 的 数据 类 型 速度 要 更 有 效率 (Hi 
如 ， 调 用 HashMap map 要 比 调 用 Map map 效率 更 高 ) 。 有 误 传 效 率 要 高 一 倍 ， 实 际 上 只 是 6% 
左右 。 而 且 ， 在 JIT 之 后 ， 他 们 直接 并 没有 大 多 差异 。 


在 没有 JIT 的 设备 上 ， 读 取 缓 存 域 比 alos 际 数 据 大 概 快 20%。 有 JIT 时 ， 域 读 取 和 本 地 读 
取 基 本 无 差 。 所 以 优化 并 不 值得 除非 你 觉得 能 让 你 的 代码 更 易 读 (这 对 final, static, static 
final 域 同样 适用 ) o 
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关于 测量 
在 优化 之 前 ， 你 应 该 确定 你 遇 到 了 性 能 问题 。 你 应 该 确保 你 能 够 准确 测量 出 现在 的 性 能 ， 否 
则 你 也 不 会 知道 优化 是 否 真 的 有 效 。 
本 章节 中 所 有 的 技巧 都 需要 Benchmark (基准 测试 ) 的 支持 。Benchmark 可 以 在 
code.google.com "dalvik" project 中 找到 


Benchmark 是 基于 Java 版 本 的 Caliper microbenchmarking 框 架 开发 的 。Microbenchmarking 
很 难 做 准确 ， 所 以 Caliper 帮 你 完成 这 部 分 工作 ， 甚 至 还 帮 你 测 了 你 没 想到 需要 测量 的 部 分 

(因为 ，VM 帮 你 管理 了 代码 优化 ， 你 很 难 知道 这 部 分 优化 有 多 大 效果 ) 。 我 们 强烈 推荐 使 用 
Caliper 来 做 你 的 基准 微 测 工作 o 


我 们 也 可 以 用 Traceview 来 测量 ， 但 是 测量 的 数据 是 没有 经 过 JIT 优 化 的 ， 所 以 实际 的 效果 应 
该 是 要 比 测量 的 数据 稍微 好 些 。 


关于 如 何 测量 与 调试 ， 还 可 以 参考 下 面 两 篇 文章 : 


e Profiling with Traceview and dmtracedump 
e Analysing Display and Performance with Systrace 


提升 Layout 的 性 能 


编写 : allenlsy - 原文 : http://developer.android.com/training/improving-layouts/index.html 


Layout 是 Android 应 用 中 直接 影响 用 户 体验 的 关键 部 分 。 如 果实 现 的 不 好 ， 你 的 Layout 会 导 
致 程序 非常 占用 内 存 并 且 UI 运行 缓慢 。Android SDK 带 有 帮助 你 找到 Layout 性 能 问题 的 工 
具 。 结 合 本 课 内 容 使 用 它 ， 你 将 学 会 使 用 最 小 的 内 存 空 间 实 现 流畅 的 Ul 。 


Lessons 


优化 Layout 的 层级 

就 像 一 个 复杂 的 网 页 会 减 慢 载 入 速度 ， 你 的 Layout 结 构 如 果 太 复杂 ， 也 会 造成 性 能 问题 。 本 
节 教 你 如 何 使 用 SDK 自 带 工具 来 查看 Layout 并 找到 性 能 瓶颈 。 

使 用 <include/> 标签 重用 Layout 

如 果 你 的 程序 的 U 在 不 同 地 方 重复 使 用 某 个 Layout， 那 本 节 将 教 你 如 何 创建 高 效 的 ， 可 重用 
的 Layout 部 件 ， 并 把 它们 “包含 "到 其 他 UI Layout 中 。 

按 需 载 入 视图 


除了 简单 的 把 一 个 Layout 包含 到 另 一 个 Layout 中 ， 你 可 能 还 想 在 程序 开始 之 后 ， 仅 当 你 的 
Layout 对 用 户 可 见 时 才 开 始 载 入 。 本 节 告 诉 你 如 何 使 用 分 步 载 入 Layout 来 提高 Layout 的 首 


次 加 载 性 能 。 


优化 ListView 的 滑动 性 能 


如 果 你 有 一 个 每 个 列表 项 (item) 都 包 
Aw 


都 包含 很 多 数据 或 者 复杂 数据 的 ListView ， 那 么 列表 滚动 的 
性 能 很 有 可 能 会 存在 问题 。 本 节 会 介绍 


多 
召 给 你 一 些 如 何 优 化 滚动 流畅 度 的 技巧 。 


优化 layout 的 层级 


编写 :allenlsy - 原文 :http://developer.android.com/training/improving-layouts/optimizing- 
layout.html 


一 个 常见 的 误区 是 ， 用 最 基础 的 Layout 结构 可 以 提高 Layout 的 性能。 然而， 因为 程序 的 每 
个 组 件 和 Layout 都 需要 经 过 初始 化 、 布 局 和 绘制 的 过 程 ， 如 果 布 局 花 套 导致 层级 过 深 ， 上 面 
的 初始 化 ， 布 局 和 绘制 操作 就 更 加 耗 时 。 例 如 ， 使 用 内 套 的 LinearLayout 可 能 会 使 得 View 
的 层级 结构 过 深 ， 此 外 ， 上 获 套 使 用 了 a weight 参数 的 LinearLayout 的 计算 量 会 尤其 
大 ， 因 为 每 个 子 元 素 都 需要 被 测量 两 次 。 这 对 需要 多 次 重复 inflate 的 Layout 尤其 需要 注意 ， 
rite tk ÆA ListView 或 GridView 时 。 


在 本 课 中 ， 你 将 学 习 使 用 Hierarchy Viewer 和 Layoutopt 来 检查 和 优化 Layout ° 


检查 Layout 
Android SDK 工具 箱 中 有 一 个 叫做 Hierarchy Viewer 的 工具 ， 能 够 在 程序 运行 时 分 析 
Layout。 你 可 以 用 这 个 工具 找到 Layout 的 性 能 瓶颈 © 


inia Viewer 4 Vid 先 择 设备 或 者 模拟 器 上 正在 运行 的 进程 ， 然 后 显示 其 Layout 的 树 型 
结构 。 每 个 块 上 的 交通 灯 分 别 代表 了 它 在 测量 、 布 局 和 绘画 时 的 性 能 ， 帮 你 找 出 瓶颈 部 分 


比如 ， 下 图 是 ListView 中 一 个 列表 项 的 Layout 。 列 表 项 里 ， 左 边 放 一 个 小 位 图 ， 右 边 是 两 个 
层 司 的 文字 。 像 这 种 需要 被 多 次 inflate 的 Layout ， 优 化 它们 会 有 事半功倍 的 效果 。 


hierarchyviewer 这 个 工具 在 <sdk>/tools/ 中 。 当 打开 时 ， 它 显示 一 张 可 使 用 设备 的 列表 ， 
和 它 正在 运行 的 组 件 。 点 击 Load View Hierarchy 来 查看 所 选 组 件 的 层级 。 比 如 ， 下 图 就 是 
前 一 个 图 中 所 示 Layout 的 层级 关系 。 








在 上 图 中 ， 你 可 以 看 到 一 个 三 层 结构 ， 其 中 右 下 角 的 TextView 在 布局 的 时 候 有 问题 。 点 击 这 
个 TextView 可 以 看 到 每 个 步骤 所 花费 的 时 间 。 


5 views 


Measure: 0.977 ms 
Layout: 0.167 ms 
Draw: 2.717 ms 





可 以 看 到 ， 泻 染 一 个 完整 的 列表 项 的 时 间 就 是 : 


测量 : 0.977ms 
布局 : 0.167ms 
绘制 : 2.717ms 


修正 Layout 


上 面 的 Layout h TA & +k E%4 LinearLayout 导致 性 能 大 慢 ， 可 能 的 解决 办 法 是 将 Layout 
层级 扁平 化 - 变 浅 变 帘 ， 而 不 是 又 窗 又 深 。RelativeaLayout 作为 根 节点 时 就 可 以 达到 目的 。 
所 以 ， 当 换 成 基于 RelativeLayout 的 设计 时 ， 你 的 Layout 变 成 了 两 层 。 新 的 Layout 变 成 这 
B 





现在 浑 染 列表 项 的 时 间 : 


e 测量 : 0.598ms 
e 布局 : 0.110ms 
e 绘制 : 2.146ms 


可 能 看 起 来 是 很 小 的 进步 ， 但 是 由 于 它 对 列表 中 每 个 项 都 有 效 ， 这 个 时 间 要 翻 倍 。 


这 个 时 间 的 ue: j- X u T4 LinearLayout 中 使 用 layout weight 所 致 ， 因 为 会 减 慢 “ 测 
量 " 的 速度 。 这 只 是 一 个 正确 使 用 各 种 Layout 的 例子 ， 当 你 使 用 layout weight NA RIA 
重 o 


使 用 Lint 


大 部 分 叫做 lint 的 编程 工具 ， 都 是 类 似 于 代码 规范 的 检测 工具 。 比 如 JSLint，CSSLinkt ， 
JSONLint 等 等 。 译 者 注 。 


运行 Lint 工具 来 检查 Layout 可 能 的 优化 方法 ， 是 个 很 好 的 实践 。Lint 已 经 取代 了 Layoutopt 
工具 ， 它 拥有 更 强大 的 功能 。Lint 中 包含 的 一 些 检测 规则 有 : 


e 使 用 compound drawable 一 用 一 个 compound drawable 替代 一 个 包含 Imageview 和 
TextView 的 LinearLayout 会 会 更 有 效率 。 

。 合并 根 frame — 如 果 FrameLayout 是 Layout 的 根 节 点 ， 并 且 没 有 使 用 padding 或 者 背 
景 等 ， 那 么 用 merge 标签 蔡 代 他 们 会 稍微 高 效 些 。 

e 没 用 的 子 节 点 一 一 个 没有 子 节点 或 者 背景 的 Layout 应 该 被 去 掉 ， 来 获得 更 扁平 的 层级 

e 没 用 的 父 节 点 一 一 个 节 点 如 果 没 有 兄弟 节 点 ， 并 且 它 不 是 scrollview 或 根 节点 ， 没 有 
人 背景， 这 样 的 节点 应 该 直接 被 子 节点 取代 ， 来 获得 更 扁平 的 层级 

e 太 深 的 Layout — Layout 的 胡 套 层 数 太 深 对 性 能 有 很 大 影响 。 党 试 使 用 更 扁平 的 Layout 
> Hike RelativeLayout 或 GridLayout 来 提高 小 性 能 。 一 般 最 多 不 超过 10 层 。 





另 一 个 使 用 Lint 的 好 处 就 是 ， 它 内 置 于 Android Studio 中 。Lint 在 你 导 编 译 程序 时 自动 运 


行 。Android Studio 中 ， 你 可 以 为 单独 的 build variant 或 者 所 有 variant 运行 lint。 


你 也 可 以 在 Android Studio 中 管理 检测 选项 ， 在 File > Settings > Project Settings 中 。 检 
测 配置 页 面 会 显示 支持 的 检测 项 目 。 


$9 0 Settings 





(a 





Appearance & Behavior 
Keymap 
Editor 

General 

Colors & Fonts 

Code Style 


Inspections 





File and Code Templates 
File Encodings 
Live Templates 
File Types 
Copyright 如 
Emmet 
Images 
Intentions 
Language Injections 加 
Spelling 8 
TODO 

Plugins 

Version Control 

Build, Execution, Deployment 
Build Tools 8 
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Editor > Inspections © For current project 





Profile: F Project Default Rd | Manage ~ | 











Description 


Multiple inspections are selected. You can edit them 


as a single inspection. 











@ )*Y £22 
Android 
General (=) 
Google Cloud Endpoints | 
Gradle a 
Groovy 口 
HTML 7 
Internationalization issues BO 
Java 口 
JavaFX m" 
JSON E 
JUnit issues 口 
Language Injection 
Manifest 
Maven 
Pattern Validation 
Properties Files 口 
RELAX NG BO 
Spelling 
TestNG BO 
XML 


Lint 有 自动 修复 、 提 示 建 议和 直接 跳 转 到 问题 处 的 功能 。 


Severity: 


Mixed 7| |In All Scopes 7 





| Cancel 


| | Help 





使 用 include 标 答 重 用 layouts 


编写 :allenlsy - 原文 :http://developer.android.com/training/improving-layouts/reusing- 


layouts.html 


虽然 Android 提供 很 多 小 的 可 重用 的 交互 组 件 ， 你 仍然 可 能 需要 重用 复杂 一 点 的 组 件 ， 这 也 
许 会 用 到 Layout。 为 了 高 效 重用 整个 的 Layout， 你 可 以 使 用 <include/> 和 <merge/> 标签 
把 其 他 Layout # A 4 ay Layout 。 


重用 Layout 非常 强大 ， 它 让 你 可 以 创建 复杂 的 可 重用 Layout。 比 如 ， 一 个 yes/no 按钮 面 
板 ， 或 者 带 有 文字 的 自 定义 进度 条 。 这 也 意味 着 ， 任 何在 多 个 Layout 中 重复 出 现 的 元 素 可 以 
被 提取 出 来 ， 被 单独 管理 ， 再 添加 到 Layout 中 。 所 以 ， 虽 然 可 以 添加 一 个 自 定 义 View KK 
现 单 独 的 UI 组 件 ， 你 可 以 更 简单 的 直接 重用 某 个 Layout 文件 。 


创建 可 重用 Layout 


如 果 你 已 经 知道 你 需要 重用 的 Layout， 就 先 创建 一 个 新 的 XML 文件 并 定义 Layout 。 比 如 ， 
以 下 是 一 个 来 自 G-Kenya codelab 的 Layout， 定 义 了 一 个 需要 添加 到 每 个 Activity 中 的 标题 
2 (titlebar.xml) : 


«FrameLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:layout width-"match parent" 
android:layout height-"wrap content" 
android: background="@color/titlebar_bg"> 


<ImageView android: layout_width="wrap_content" 
android: layout_height="wrap_content" 
android: src="@drawable/gafricalogo" /> 
</FrameLayout> 


根 节点 View 就 是 你 想 添加 入 的 Layout 类 型 。 


A 


使 用 <include> 标签 


使 用 <include> 标签 ， 可 以 在 Layout 中 添加 可 重用 的 组 件 。 比 如 ， 这 里 有 一 个 来 自 G- 
Kenya codelab 的 Layout 需要 包含 上 面 的 那个 标题 栏 : 


«LinearLayout xmlns:android-"http://schemas.android.com/apk/res/android" 
android:orientation-"vertical" 
android:layout width-"match parent" 
android:layout height-"match parent" 
android: background="@color/app_bg" 
android: gravity="center_horizontal"> 


<include layout="@layout/titlebar"/> 


<TextView android:layout width-"match parent" 
android:layout height-"wrap content" 
android: text="@string/hello" 
android: padding="10dp" /> 


</LinearLayout> 


你 也 可 以 履 写 被 添加 的 Layout 的 所 有 Layout 参数 (任何 android:layout * 属性 ) ， 通 过 在 
<include/> 中 声明 他 们 来 完成 。 比 如 : 


«include android:id-"Q-id/news title" 
android: layout_width="match_parent" 
android:layout height-"match parent" 
layout="@layout/title"/> 


然而 ， 如 果 你 要 在 <include> PHS JB, VE > URSA FAH] android: layout_height 和 


android:layout width ° 


使 用 «merge» 标签 


«merge /> tS EMRE Layout 时 取消 了 UI ZAP CAA ViewGroup ° 比如， 如 果 你 有 一 

A Layout 是 一 个 坚 直 方向 的 get ， 其 中 包含 两 个 连续 的 View 可 以 在 别 的 Layout 中 
ub ， 那么 你 会 做 一 个 LinearLayout 来 包含 这 两 个 View ， 以 便 重 用 。 不 过 ， 当 使 用 一 个 
LinearLayout 作为 另 一 个 LinearLayout "m AN 44 LinearLayout 4) Zr AM T xU 
你 的 Ul 性 能 外 没有 任何 意义 。 


为 了 避免 这 种 情况 ， 你 可 以 用 <merge> 元 素来 替代 可 重用 Layout 的 根 节 点 。 例 如 : 


«merge xmlns:android-"http://schemas.android.com/apk/res/android"» 


«Button 
android:layout width-"fill parent" 
android:layout height-"wrap content" 
android: text="@string/add"/> 


<Button 
android: layout_width="fill_parent" 
android: layout_height="wrap_content" 
android: text="@string/delete"/> 


</merge> 


现在 ， 当 你 要 将 这 个 Layout 包含 到 另 一 个 Layout PH (并 且 使 用 了 <include/s> 标签 ) ， 
系统 会 忽略 «merge» 标签 ， 直 接 把 两 个 Button 放 到 Layout «include» 的 所 在 位 置 。 


按 需 加 载 视图 


编写 :allenlsy - Æ xc:http://developer.android.com/training/improving-layouts/loading- 
ondemand.html 


有 时 你 的 Layout 会 用 到 不 怎么 重用 的 复杂 视图 。 不 管 它 是 列表 项 细节 ， 进 度 显示 器 ， 或 是 撤 
销 时 的 提示 信息 ， 你 可 以 仅 在 需要 的 时 候 载 入 它们 ， 提 高 UE 


Æ 3i ViewStub 


ViewStub 是 一 个 轻 量 的 视图 ， 不 需要 大 小 信息 ， 也 不 会 在 被 加 入 的 Layout 中 绘制 任何 东 
西 。 每 个 ViewStub 只 需要 设置 android:layout 属性 来 指定 需要 被 inflate 的 Layout 类 型 。 


以 下 ViewStub 是 一 个 半 透 明 的 进度 条 履 盖 层 。 功 能 上 讲 ， 它 应 该 只 在 新 的 数据 项 被 导入 到 应 
用 程序 时 可 见 


«ViewStub 
android: id="@+id/stub_import" 
android: inflatedId="@+id/panel_import" 
android: layout="@layout/progress_overlay" 
android:layout width-"fill parent" 
android:layout height-"wrap content" 
android:layout gravity-"bottom" /> 


# ^. ViewStub Layout 


当 你 要 载 入 用 ViewStub 声明 的 Layout 时 ， 要 么 用 setvisibility(View.VISIBLE) 设置 它 的 可 
见 性 ， 要 么 调用 其 inflate) 方法 。 


((ViewStub) findViewById(R.id.stub import)).setVisibility(View.VISIBLE); 
// or 
View importPanel - ((ViewStub) findViewById(R.id.stub import)).inflate(); 


Notes : inflate() 方法 会 在 泻 染 完成 后 返回 被 inflate 的 视图 ， 所 以 如 果 你 需要 和 这 个 
Layout 交互 的 话 ， 你 不 需要 再 调用 findviewById() 去 查找 这 个 元 素 ，。 


一 旦 ViewStub 可 见 或 是 被 inflate 了 ，ViewStub 就 不 再 继续 存在 View 的 层级 机 构 中 了 。 取 而 
代 之 的 是 被 inflate 的 Layout， 其 id 是 ViewStub 上 的 android:inflatedId 属性 。 
(ViewStub 的 android:id 属性 仅 在 ViewStub 可 见 以 前 可 用 ) 


Notes : ViewStub 的 一 个 缺陷 是 ， 它 目前 不 支持 使 用 <merge/> 标签 的 Layout 。 
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使 得 ListView 滑 动 顺畅 


编写 :allenlsy - Æ xc:http://developer.android.com/training/improving-layouts/smooth- 
scrolling.html 


保持 程序 流畅 的 关键 ， 是 让 主线 程 (ULAR) 不 要 进行 大 量 运 算 。 你 要 确保 在 其 他 线程 执行 
磁盘 读 写 、 网 络 读 写 或 是 SQL 操作 等 。 为 了 测试 你 的 应 用 的 状态 ， 你 可 以 启用 StrictMode » 


使 用 后 台 线 程 


你 应 该 把 主线 程 中 的 耗 时 间 的 操作 ， 提 取 到 一 个 后 台 线 程 (也 叫做 “worker thread 工 作 线 程 ”) 
中 ， 使 得 主线 程 只 关注 UI 绘画 。 很 多 时 候 ， 使 用 AsyncTask 是 一 个 简单 的 在 主线 程 以 外 进行 
操作 的 方法 。 系 统 会 自动 把 execute() 的 请 求 放 入 队列 中 并 线性 调用 执行 。 这 个 行为 是 全 局 
的 ， 这 意味 着 你 不 需要 考虑 自己 定义 线程 池 的 事情 。 


在 下 面 的 例子 中 ， 一 个 AsyncTask 被 用 于 在 后 台 线 程 载 入 图 片 ， 并 在 载 入 完成 后 把 图 片 显示 
到 UI 上 。 当 图 片 正 在 载 入 时 ， 它 还 会 显示 一 个 进度 提示 。 


// Using an AsyncTask to load the slow images in a background thread 
new AsyncTask<ViewHolder, Void, Bitmap>() { 
private ViewHolder v; 


@Override 

protected Bitmap doInBackground(ViewHolder... params) { 
v = params[0]; 
return mFakeImageLoader .getImage(); 


@Override 
protected void onPostExecute(Bitmap result) { 
super .onPostExecute(result); 
if (v.position == position) { 
// If this item hasn't been recycled already, hide the 
// progress and set and show the image 
v.progress.setVisibility(View.GONE); 
v.icon.setVisibility(View.VISIBLE); 
v.icon.setImageBitmap(result); 


} 


}.execute(holder); 


从 Android 3.0 (API level 11) 开始 , AsyncTask 有 个 新 特性 ， 那 就 是 它 可 以 在 多 个 CPU KE 
运行 。 你 可 以 调用 executeOnExecutor ( ) 而 不 是 execute() ， 前 者 可 以 根据 CPU 的 核心 数 来 触 
发 多 个 任务 同时 进行 。 


在 ViewHolder 中 填 入 视图 对 象 


你 的 代码 可 能 在 ListView 滑动 时 经 常 使 用 findviewByrd() ， 这 样 会 降低 性 能 。 即 使 是 
Adapter 返回 一 个 用 于 回收 的 inflate 后 的 视图 ， 你 仍然 需要 查看 这 个 元 素 并 更 新 它 。 避 免 频 
繁 调 用 findviewById() 的 方法 之 一 ， 就 是 使 用 ViewHolder (视图 占 位 符 ) 的 设计 模式 。 


一 个 ViewHolder 对 象 存 储 了 他 的 标签 下 的 每 个 视图 。 这 样 你 不 用 频繁 查找 这 个 元 素 。 第 一 ， 
你 需要 创建 一 个 类 来 存储 你 会 用 到 的 视图 。 比 如 : 


static class ViewHolder { 
TextView text; 
TextView timestamp; 
ImageView icon; 
ProgressBar progress; 
int position; 


然后 ， 在 Layout 的 类 中 生成 一 个 ViewHolder 对 象 : 


ViewHolder holder = new ViewHolder(); 

holder.icon - (ImageView) convertView.findViewById(R.id.listitem image); 
holder.text - (TextView) convertView.findViewById(R.id.listitem text); 
holder.timestamp - (TextView) convertView.findViewById(R.id.listitem timestamp); 
holder.progress - (ProgressBar) convertView.findViewById(R.id.progress spinner); 
convertView.setTag(holder); 


这 样 你 就 可 以 轻松 获取 每 个 视图 ， 而 不 是 使 用 findviewById() 来 不 断 查找 子 视 图 ， 节 省 了 宝 
贵 的 运算 时 间 。 


优化 电池 寿命 


编写 :kesenhoo - 原文 :http://developer.android.com/training/monitoring-device- 
state/index.html 


显然 ， 手 持 设 备 的 电量 使 用 情况 需要 引起 很 大 的 重视 。 通 过 这 一 系列 的 课程 ， 你 将 学 会 如 何 
根据 设备 的 状态 来 改变 App 的 某 些 行为 与 功能 。 


通过 在 失去 网 络 连接 时 关闭 后 台 更 新 服务 ， 在 剩余 电量 较 低 时 减少 更 新 数据 的 频率 等 操作 ， 
你 可 以 在 不 影响 用 户 体验 的 前 提 下 ， 确 保 App 对 电池 寿命 的 影响 减 到 最 小 。 


课程 


检测 电量 与 充电 状态 


学 习 如 何 通过 判断 与 检测 当前 电池 电量 以 及 充电 状态 的 变化 ， 改 变 应 用 程序 的 更 新 频率 。 


判断 并 监测 设备 的 底座 状态 与 类 型 


设备 使 用 习惯 的 区 别 也 会 影响 到 刷新 频率 的 优化 措施 ， 这 节 课 中 将 学 习 如 何 判断 与 监测 底座 
状态 及 其 种 类 来 改变 应 用 程序 的 行为 。 


判断 并 检测 网 络 连 接 状 态 


在 没有 连接 到 互联 网 的 情况 下 ， 你 是 无 法 在 线 更 新 应 用 的 。 这 一 节 课 将 学 习 如 何 根据 网 络 的 
连接 状态 ， 改 变 后 台 更 新 的 频率 ， 以 及 如 何在 高 带宽 传输 任务 开始 前 ， 判 断 网 络 连 接 类 型 (Wi- 
Fi/ 数 据 连接 )。 


按 需 操纵 BroadcastReceiver 


在 Manifest 清 单 文 件 中 声明 的 BroadcastReceiver 可 以 在 运行 时 切换 其 开 司 状态 ， 这 样 一 来 ， 
我 们 就 可 以 根据 当前 设备 的 状态 ， 人 禁用 那些 没有 必要 开局 的 BroadcastReceiver。 在 这 一 节 课 
将 学 习 如 何 通过 切换 这 些 BroadcastReceiver 的 开局 状态 ， 以 及 如 何 根 据 设 备 的 状态 延迟 某 一 
操作 的 执行 时 机 ， 来 提高 应 用 的 效率 。 


优化 电池 寿命 
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监测 电池 的 电量 与 充电 状态 


编写 :kesenhoo - 原文 :http://developer.android.com/training/monitoring-device- 
state/battery-monitoring.html 


当 你 想 通 过 改变 后 台 更 新 操作 的 频率 来 减少 对 电池 寿命 的 影响 时 ， 那 么 首先 需要 检查 当前 电 
量 与 充电 状态 。 


执行 应 用 更 新 对 电池 寿命 的 影响 是 与 电量 和 充电 状态 密切 相关 的 。 当 使 用 交流 电 对 设备 充电 
时 ， 更 新 操作 的 影响 可 以 忽略 不 计 ， 所 以 在 大 多 数 情 况 下 ， 如 果 使 用 壁 式 充电 器 对 设备 进行 
充电 ， 我 们 可 以 将 刷新 频率 设置 到 最 大 。 相 反 的 ， 如 果 设 备 没有 在 充电 状态 ， 那 么 我 们 就 需 
要 尽量 减少 设备 的 更 新 操作 来 延长 电池 的 续航 能 力 。 


同样 的 ， 如 果 我 们 监测 到 电量 即将 耗 尽 时 ， 那 么 应 该 尽 可 能 降低 甚至 停止 更 新 操作 。 


判断 当前 充电 状态 


首先 来 看 一 下 应 该 如 何 确定 当前 的 充电 状态 。BatteryManager 会 广播 一 个 带 有 电池 与 充电 详 
情 的 Sticky Intent 


因为 广播 的 是 一 个 sticky Intent， 所 以 不 需要 注册 BroadcastReceiver。 仅 仅 只 需要 调用 一 个 
以 null 作为 Receiver 参 数 的 registerReceiver() 方法 就 可 以 了 。 如 下 面 的 代码 片段 中 展示 的 
那样 ， 它 返回 了 保存 当前 电池 信息 的 Intent。 你 也 可 以 在 这 里 传 入 一 个 实际 的 
BroadcastReceiver 对 象 ， 但 这 并 不 是 必须 的 。 


IntentFilter ifilter = new IntentFilter(Intent.ACTION BATTERY CHANGED); 
Intent batteryStatus - context.registerReceiver(null, ifilter); 


我 们 可 以 提取 出 当前 的 充电 状态 ， 以 及 设备 处 于 充电 时 ， 是 通过 USB 还 是 交流 充电 器 充电 
的 。 


// Are we charging / charged? 

int status = batteryStatus.getIntExtra(BatteryManager.EXTRA STATUS, -1); 

boolean isCharging - status -- BatteryManager.BATTERY STATUS CHARGING || 
status -- BatteryManager.BATTERY STATUS FULL; 


// How are we charging? 

int chargePlug = batteryStatus.getIntExtra(BatteryManager.EXTRA PLUGGED, -1); 
boolean usbCharge - chargePlug -- BatteryManager.BATTERY PLUGGED USB; 

boolean acCharge - chargePlug -- BatteryManager.BATTERY PLUGGED AC; 


， 我 们 可 以 在 设备 使 用 交流 充电 时 最 大 化 后 台 更 新 频率 ， 在 使 用 USB 充 电 时 降低 更 新 频 
率 ， 在 非 充 电 状态 时 ， 将 更 新 频率 进一步 降低 。 


监测 充电 状态 的 改变 


充电 状态 随时 可 能 改变 ， 所 以 我 们 应 该 检查 充电 状态 的 改变 来 调整 更 新 频率 。 


BatteryManager 会 在 设备 连接 或 者 断 开 充 电器 的 时 候 广 播 一 个 Action。 即 使 应 用 没有 运行 ， 我 
们 也 应 该 接收 这 些 事件 的 广播 ， 主 要 原因 是 因为 这 些 事件 会 影响 到 应 用 局 动 (从 而 进行 更 
新 ) 的 频 府 ， 因 此 我 们 应 该 在 Manifest 文 件 里 面 注 册 一 个 BroadcastReceiver 来 监听 含 

有 ACTION_POWER_CONNECTED 与 ACTION_POWER_DISCONNECTED 的 Intent 。 


«receiver android:name=".PowerConnectionReceiver"> 
<intent-filter> 
«action android:name-"android.intent.action.ACTION POWER CONNECTED"/» 
«action android:name-"android.intent.action.ACTION POWER DISCONNECTED'/» 
</intent-filter> 


</receiver> 


我 们 可 以 在 该 BroadcastReceiver 的 实现 中 ， 提 取出 当前 的 充电 状态 ， 如 下 所 示 : 


public class PowerConnectionReceiver extends BroadcastReceiver ( 
@Override 
public void onReceive(Context context, Intent intent) { 
int status = intent.getIntExtra(BatteryManager.EXTRA_STATUS, -1); 
boolean isCharging = status == BatteryManager.BATTERY STATUS CHARGING | | 
status == BatteryManager.BATTERY STATUS FULL; 


int chargePlug = intent.getIntExtra(BatteryManager.EXTRA PLUGGED, -1); 
boolean usbCharge - chargePlug -- BatteryManager.BATTERY PLUGGED USB; 
boolean acCharge - chargePlug -- BatteryManager.BATTERY PLUGGED AC; 


判断 当前 电池 电量 


在 一 些 情况 下 ， 获 取 到 当前 电池 电量 也 很 有 帮助 。 我 们 可 以 在 获知 电量 少 于 甘 个 级 别 的 时 候 
减少 后 台 的 更 新 频率 。 我 们 可 以 通过 电池 状态 Intent 获 取 到 电池 电量 与 容量 等 信息 ， 如 下 所 
示 : 


int level = batteryStatus.getIntExtra(BatteryManager.EXTRA LEVEL, -1); 
int scale = batteryStatus.getlIntExtra(BatteryManager.EXTRA SCALE, -1); 


float batteryPct = level / (float)scale; 


检测 电量 的 有 效 改 变 


我 们 不 能 不 停 地 监测 电池 状态 ， 实 际 上 这 也 是 不 必要 的 。 通 常 来 说 ， 不 间断 地 监测 电量 信息 
对 电池 的 影响 会 远大 于 应 用 本 身 对 电池 的 影响 。 所 以 我 们 应 该 仅 监 测 电量 的 一 些 显著 性 变 
化 ， 特 别 是 当 设 备 进入 或 者 离开 低 电 量 状态 时 。 


在 下 面 的 Manifest 文 件 片 段 中 ，BroadcastReceiver 仅 仅 监 
"T ACTION BATTERY. LOW 与 ACTION BATTERY OKAY ， 这 样 它 就 只 会 在 设备 电量 进入 低 电 量 或 者 离 


开 低 电量 的 时 候 被 触发 。 


«receiver android:name-".BatteryLevelReceiver"- 

<intent-filter> 
<action android:name="android.intent.action.ACTION_BATTERY_LOW"/> 
<action android:name="android.intent.action.ACTION_BATTERY_OKAY"/> 
</intent-filter> 


</receiver> 


通常 我 们 都 需要 在 进入 低 电 量 的 情况 下 ， 关 闭 所 有 后 台 更 新 来 维持 设备 的 续航 ， 因 为 这 个 时 
候 做 任何 更 新 等 操作 都 极 有 可 能 是 无 用 的 ， 因 为 也 许 在 你 还 没 来 得 及 处 理 更 新 的 数据 时 ， 设 
备 就 因 电 量 耗 尽 而 自动 关机 了 。 


在 很 多 时 候 ， 用 户 往往 会 将 设备 放 入 某 种 底座 中 充电 《译注 : 比如 车 载 的 底座 式 充电 器 ) ， 
在 下 一 节 课 程 当 中 ， 我 们 将 会 学 习 如 何 确 定 当前 的 底座 状态 ， 以 及 如 何 监听 设备 底座 的 变 
化 。 


判断 并 监测 设备 的 底座 状态 与 类 型 


编写 :kesenhoo - 原文 :http://developer.android.com/training/monitoring-device- 
state/connectivity-monitoring.html 


Android 设 备 可 以 放置 在 许多 不 同 的 底座 中 ， 包 括 车 载 底 座 ， 家 庭 底座 还 有 数字 信号 底座 以 及 
模拟 信号 底座 等 。 由 于 许多 底座 会 向 设备 充电 ， 因 此 底座 状态 通常 与 充电 状态 密切 相关 。 


你 的 应 用 类 型 决定 了 底座 类 型 会 对 更 新 频率 产生 怎样 的 影响 。 对 于 一 个 体育 类 应 用 ， 可 以 让 
设备 在 笔记 本 底座 状态 下 增加 更 新 的 频率 ， 或 者 当 设 备 在 车 载 底 座 状 态 下 停止 更 新 。 相 反 
的 ， 如 果 你 的 后 台 服 务 用 来 更 新 交通 数据 ， 你 也 可 以 选择 在 车 载 底 座 模式 下 最 大 化 更 新 的 频 
A 。 


底座 状态 也 是 以 Sticky Intent 方 式 来 广播 的 ， 这 样 可 以 通过 查询 Intent 里 面 的 数据 来 判断 目前 
设备 是 否 放置 在 底座 中 ， 以 及 底座 的 类 型 。 


判断 当前 底座 状态 


底座 状态 的 具体 信息 会 以 Extra 数 据 的 形式 ， 包 含 在 具有 ACTION_DOCK_EVENT 这 一 Action 
的 某 个 Sticky 广 播 中 ， 因 此 ， 你 不 需要 为 其 注册 一 个 BroadcastReceiver。 如 下 所 示 ， 仅 需要 
将 null 作为 参数 传递 给 registerReceiver() 方 法 就 可 以 了 : 


IntentFilter ifilter = new IntentFilter(Intent.ACTION DOCK EVENT); 
Intent dockStatus = context.registerReceiver(null, ifilter); 


你 可 以 从 ExTRA Dock srArE 这 一 Extra 数 据 中 ， 提 取出 当前 的 底座 状态 : 


int dockState = battery.getIntEXxtra(EXTRA DOCK STATE, -1); 
boolean isDocked - dockState !- Intent.EXTRA DOCK STATE UNDOCKED; 


判断 当前 底座 类 型 


如 果 设 备 被 放置 在 了 底座 中 ， 那 么 它 可 以 有 下 面 四 种 底座 类 型 : 


e Car 

e Desk 

e Low-End (Analog) Desk 
e High-End (Digital) Desk 


注意 最 后 两 种 底座 类 型 仅 在 API Level 11 及 以 后 版 本 的 Android 系 统 中 才 被 支持 。 如 果 你 只 在 
乎 底座 的 类 型 而 不 管 它 是 数字 的 还 是 模拟 的 ， 那 么 可 以 仅 监 测 三 种 类 型 : 


boolean isCar = dockState == EXTRA DOCK STATE CAR; 

boolean isDesk - dockState -- EXTRA DOCK STATE DESK || 
dockState == EXTRA DOCK STATE LE DESK || 
dockState == EXTRA DOCK STATE HE DESK; 








监测 底座 状态 或 者 类 型 的 改变 


当 设 备 被 放置 在 或 者 拔 出 底座 时 ， 系 统 会 发 出 一 个 具有 ACTION DOCK _EVENT 这 
广播 。 为 了 监听 底座 状态 的 变化 ， 我 们 只 需要 在 应 用 的 Manifest 文 件 中 注册 一 个 


BroadcastReceiver， 如 下 所 示 : 


这 一 Action 的 


<action android:name="android.intent.action.ACTION DOCK_EVENT"/> 


之 于 该 BroadcastReceiver 的 具体 实现 ， 可 以 参考 前 面 提 到 的 那些 方法 ， 以 此 来 提取 出 当前 的 
底座 类 型 和 状态 。 


判断 并 监测 风 网 络 连接 状态 


编写 :kesenhoo - 原文 :http://developer.android.com/training/monitoring-device- 
state/connectivity-monitoring.html 
重复 闹钟 和 后 台 服 务 最 常见 的 功能 之 一 ， 是 用 来 从 网 络 上 获取 应 用 更 新 ， 存 储 数据 或 者 执行 
大 文件 的 下 载 。 但 是 如 果 没 有 获得 网 络 连接 ， 或 者 连接 的 速度 太 慢 以 至 于 下 载 无 法 完成 ， 那 
么 就 没有 必要 唤醒 设备 并 执行 那些 更 新 等 操作 了 。 
我 们 可 以 使 用 ConnectivityManager 来 检查 设备 是 否 连接 到 网 络 ， 以 及 网 络 的 类 型 (译注 : 通 
过 网 络 的 连接 状况 改变 ， 相 应 的 改变 app 的 行为 ， 减 少 无 谓 的 操作 ， 从 而 延长 设备 的 续航 能 
JH)» 


判断 当前 是 否 有 网 络 


如 果 没 有 网 络 连 接 ， 那 么 就 没有 必要 做 那些 需要 联网 的 事情 。 下 面 的 代码 片段 展示 了 如 何 通 
过 ConnectivityManager 检 查 当 前 活动 的 网 络 类 型 ， 并 确定 它 是 否 可 以 连接 到 互联 网 : 


ConnectivityManager cm = 
(ConnectivityManager)context.getSystemService(Context.CONNECTIVITY SERVICE); 


NetworkInfo activeNetwork - cm.getActiveNetworkInfo(); 


boolean isConnected - activeNetwork !- null && 
activeNetwork.isConnectedOrConnecting(); 


判断 连接 网 络 的 类 型 


我 们 还 可 以 获取 到 当前 的 网 络 连 接 类 型 。 


设备 通常 可 以 有 移动 网 络 ，WiMax，Wi-Fi 与 以 太 网 连接 等 类 型 。 通 过 查询 当前 活动 的 网 络 类 
型 ， 可 以 根据 网 络 的 带宽 对 更 新 频率 进行 调整 : 


boolean isWiFi = activeNetwork.getType() == ConnectivityManager.TYPE WIFI; 


移动 网 络 的 使 用 nae ， 所 以 多 数 情况 下 ， 如 果 设 备 正在 使 用 移动 网 络 ， 我 们 应 该 
减少 应 用 的 更 新 频率 ; 同样 地 ， 还 应 该 临时 地 挂 起 一 些 文件 下 载 任务 直到 有 Wi-Fi 连 接 时 再 继 
续 下 载 。 


如 果 已 经 关闭 了 更 新 操作 ， 那 么 需要 监听 网 络 连接 的 变化 ， 这 样 就 可 以 在 建立 了 互联 网 访问 
之 后 ， 重 新 恢复 它们 。 


监听 网 络 连接 的 变化 


当 网 络 连接 发 生 改 变 时 ，ConnectivityManager 会 广播 

CONNECTIVITY ACTION ( android.net.conn.CONNECTIVITY_CHANGE ) 的 Action 消 息 。 我 们 可 
以 在 Manifest 文 件 里 面 注册 一 个 BroadcastReceiver， 来 监听 这 些 变化 ， 并 适当 地 恢复 (或 挂 
起 ) 你 的 后 台 更 新 


«action android:name="android.net.conn.CONNECTIVITY_CHANGE"/> 


设备 的 网 络 变化 可 能 会 比较 频繁 ， 因 此 每 当 你 在 移动 网 络 与 Wi-Fi 之 间 切 换 的 时 候 ， 这 一 广播 
就 会 被 触发 。 因 此 ， 我 们 可 以 仅 在 之 前 的 更 新 或 者 下 载 任务 被 挂 起 的 时 候 去 监听 这 一 广播 
(用 来 恢复 那些 任务 ) 。 通 常 我 们 可 以 在 开始 更 新 前 检查 一 下 网 络 连接 ， 如 果 当 前 没有 连接 
到 互联 网 ， 那么 就 将 更 新 任务 挂 起 ， 直 到 连接 恢复 。 


Lit FAH BS Broadcast Receiver 开 启 状 态 的 切换 ， 这 一 内 容 会 在 下 一 节 课 中 展开 。 


按 需 操控 BroadcastReceiver 


编写 :kesenhoo - /$ x-:http://developer.android.com/training/monitoring-device- 
state/manifest-receivers.html 


监测 设备 状态 变化 最 简单 的 方法 ， 是 为 你 所 要 监听 的 每 一 个 状态 创建 一 
个 BroadcastReceiver， 并 在 Manifest 文 件 中 注册 它们 。 之 后 就 可 以 在 每 一 个 
BroadcastReceiver 中 ， 根 据 当 前 设备 的 状态 调整 一 些 计划 任务 


上 迹 方法 的 副作用 是 : 一 旦 你 的 接收 器 收 到 了 广播 ， 应 用 就 会 唤醒 设备 。 唤 醒 的 频率 可 能 会 
远 高 于 需要 的 频率 


更 好 的 方法 是 在 程序 运行 时 开启 或 者 关闭 BroadcastReceiver。 这 样 的 话 ， 你 就 可 以 让 这 些 接 
收 器 仅 在 需要 的 时 候 被 激活 。 


切换 是 否 开局 接收 器 以 提 痪 效率 


我 们 可 以 使 用 PackageManager 来 切换 任何 一 个 在 Mainfest 里 面 定 义 好 的 组 件 的 开局 状态 。 通 
过 下 面 的 方法 可 以 开启 或 者 关闭 任何 一 个 BroadcastReceiver : 

ComponentName receiver = new ComponentName(context, myReceiver.class); 

PackageManager pm = context.getPackageManager(); 

pm.setComponentEnabledSetting(receiver, 


PackageManager.COMPONENT ENABLED STATE ENABLED, 
PackageManager.DONT KILL APP) 


使 用 这 种 技术 ， 如 果 我 们 确定 网 络 连接 已 经 断 开 ， 那 么 可 以 在 这 个 时 候 关 闭 除 了 监听 网 络 状 
态 变化 的 接收 器 之 外 的 其 它 所 有 接收 器 。 


相反 的 ， 一 旦 重新 建立 网 络 连接 ， 我 们 可 以 停止 监听 网 络 连接 的 改变 ， 而 仅仅 在 执行 需要 联 
网 的 操作 之 前 判断 当前 网 络 是 否 可 以 用 。 


同样 地 ， 你 可 以 使 用 上 面 的 技术 来 暂缓 一 个 需要 更 高 带宽 的 下 载 任 务 。 这 仅 需要 局 用 一 个 监 
听 网 络 连 接 变化 的 BroadcastReceiver， 并 在 连接 到 Wi-Fi 时 ， 初 始 化 下 载 任务 


多 线程 操作 


编写 :AllenZheng1991 - 原文 :http://developer.android.com/training/multiple- 
threads/index.html 


把 一 个 相对 耗 时 且 数据 操作 复杂 的 任务 分 割 成 多 个 小 的 操作 ， 然 后 分 别 运行 在 多 个 线程 上 ， 
这 能 够 提高 完成 任务 的 速度 和 效率 。 在 多 核 CPU 的 设备 上 ， 系 统 可 以 并 行 运行 多 个 线程 ， 而 
不 需要 让 每 个 子 操作 等 待 CPU 的 时 间 片 切换 。 例 如 ， 如 果 要 解码 大 量 的 图 片 文件 并 以 缩 略图 
的 形式 把 图 片 显示 在 屏幕 上 ， 当 你 把 每 个 解码 操作 单独 用 一 个 线程 去 执行 时 ， 会 发 现 速 度 快 
了 很 多 。 


这 个 章节 会 向 你 展示 如 何在 一 个 Android 应 用 中 创建 和 使 用 多 线程 ， 以 及 如 何 使 用 线程 池 对 象 
(thread pool object) 。 你 还 将 了 解 到 如 何 使 得 代码 运行 在 指定 的 线程 中 ， 以 及 如 何 让 你 创 
建 的 线程 和 UI 线程 进行 通信 。 


Sample Code 


点 击 下 载 : ThreadSample 


Lessons 


在 一 个 线程 中 执行 一 段 特定 的 代码 


学 习 如 何 通过 实现 Runnable 接 口 定义 一 个 线程 类 ， 让 你 写 的 代码 能 在 单独 的 一 个 线程 中 执 


为 多 线程 创建 线程 池 


习 如 何 创 建 一 个 能 管理 线程 池 和 任务 队列 的 对 象 ， 需 要 使 用 一 个 叫 ThreadPoolExecutor 的 


类 o 

在 线程 池 中 的 一 个 线程 里 执行 代码 
学 习 如 何 让 线程 池 里 的 一 个 线程 执行 一 个 任务 。 
与 UI 线程 通信 


学 习 如 何 让 线程 池 里 的 一 个 普通 线程 与 UI 线程 进行 通信 。 


多 线程 操作 
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在 一 个 线程 中 执行 一 段 特 定 的 代码 


编写 :AllenZheng1991 - 原文 :http://developer.android.com/training/multiple- 


threads/define-runnable.html 
这 一 课 向 你 展示 了 如 何 通过 实现 Runnable 接 口 得 到 一 个 能 在 重 写 的 Runnable.run() 方法 中 执 
行 一 段 代码 的 单独 的 线程 。 另 外 你 可 以 传递 一 个 Runnable 对 象 到 另 一 个 对 象 ， 然 后 这 个 对 象 
可 以 把 它 附 加 到 一 个 线程 ， 并 执行 它 。 一 个 或 多 个 执行 特定 操作 的 Runnable 对 象 有 时 也 被 称 


为 一 个 任务 。 
Thread 和 Runnable 只 是 两 个 基本 的 线程 类 ， 通 过 他 们 能 发 挥 的 作用 有 限 ， 但 是 他 们 是 强大 的 
Android 线 程 类 的 基础 类 ， 例 如 Android 中 的 HandlerThread, AsyncTask 和 |ntentService 都 是 以 


它们 为 基础 。Thread 和 Runnable 同 时 也 是 ThreadPoolExecutor 类 的 基 
础 。ThreadPoolExecutor 类 能 自动 管理 线程 和 任务 队列 ， 其 至 可 以 并 行 执 行 多 个 线程 。 


N 


> y Np 3 3 

定义 一 个 实现 Runnable 接 口 的 类 

直接 了 当 的 方法 是 通过 实现 Runnable 接 口 去 定义 一 个 线程 类 。 例 如 : 
public class PhotoDecodeRunnable implements Runnable { 


@Override 
public void run() { 
pui 


* 把 你 想 要 在 线程 中 执行 的 代码 写 在 这 里 


5 


实现 run() 方 法 


在 一 个 类 里 ， Runnable.run() 包含 执行 了 的 代码 。 通 常 在 Runnable 中 执行 任何 操作 都 是 可 
以 的 ， 但 需要 记 住 的 是 ， 因 为 Runnable 不 会 在 UI 线程 中 运行 ， 所 以 它 不 能 直接 更 新 UI 对 象 ， 
例如 View 对 和 象 。 为 了 与 Ul 对 象 进 行 通信 ， 你 必须 使 用 另 一 项 技术 ， 在 与 UI 线 程 进行 通信 这 一 


课 中 我 们 会 对 其 进行 描述 。 


在 Runnable.run()) 方 法 的 开始 的 地 方 通过 调用 参数 为 THREAD_PRIORITY_BACKGROUND 
的 Process.setThreadPriority() 方 法 来 设置 线程 使 用 的 是 后 台 运 行 优 先 级 。 这 个 方法 减少 了 通 
过 Runnable 创 建 的 线程 和 和 UI 线程 之 间 的 资源 竞争 。 


你 还 应 该 通过 在 Runnable</a> 自身 中 调用 Thread.currentThread() 来 存储 一 个 引用 到 
Runnable 对 象 的 线程 。 


下 面 这 段 代 码 展 示 了 如 何 创建 run() 方 法 : 


class PhotoDecodeRunnable implements Runnable { 


* 定义 要 在 这 个 任务 中 执行 的 代码 
hf. 
@Override 
public void run() { 
// 把 当前 的 线程 变 成 后 台 执 行 的 线程 
android.os.Process.setThreadPriority(android.os.Process.THREAD PRIORITY BACKGR 
OUND) ; 


s 
* 在 PhotoTask 实 例 中 存储 当前 线程 ， 以 至 于 这 个 实例 能 中 断 这 个 线程 
i 
mPhotoTask.setlImageDecodeThread(Thread.currentThread()); 


为 多 线程 创建 管理 器 


编写 :AllenZheng1991 - Æ X :http://developer.android.com/training/multiple- 
threads/create-threadpool.html 


在 前 面 的 课程 中 展示 了 如 何在 单独 的 一 个 线程 中 执行 一 个 任务 。 如 果 你 的 线程 只 想 执行 一 
次 ， 那 么 上 一 课 的 内 容 已 经 能 满足 你 的 需要 了 。 


如 果 你 想 在 一 个 数据 集中 重复 执行 一 个 任务 ， 而 且 你 只 需要 一 个 执行 运行 一 次 。 这 时 ， 使 用 
一 个 IntentService 将 能 满足 你 的 需求 。 为 了 在 资源 可 用 的 的 时 候 自动 执行 任务 ， 或 者 允许 不 
同 的 任务 同时 执行 (或 前 后 两 者 ) ， 你 需要 提供 一 个 管理 线程 的 集合 。 为 了 做 这 个 管理 线程 
的 集合 ， 使 用 一 个 ThreadPoolExecutor 实 例 ， 当 一 个 线程 在 它 的 线程 池 中 变 得 不 受 约束 时 ， 
它 会 运行 队列 中 的 一 个 任务 。 为 了 能 执行 这 个 任务 ， 你 所 需要 做 的 就 是 把 它 加 入 到 这 个 队 
列 。 


一 个 线程 池 能 运行 多 个 并 行 的 任务 实例 ， 因 此 你 要 能 保证 你 的 代码 是 线程 安全 的 ， 从 而 你 需 
要 给 会 被 多 个 线程 访问 的 变量 附 上 同步 代码 块 (synchronized block) « 当 一 个 线程 在 对 一 个 变 
量 进行 写 操作 时 ， 通 过 这 个 方法 将 能 阻止 另 一 个 线程 对 该 变量 进行 读 取 操作 。 典型 的 ， 这 种 
情况 会 发 生 在 静态 变量 上 ， 但 同样 它 也 能 突然 发 生 在 任意 一 个 只 实例 化 一 次 。 为 了 学 到 更 多 
的 相关 知识 ， ua 阅读 进程 与 线程 这 一 API 指 南 。 


、 > ds uh ck 

定义 线程 池 类 

在 自己 的 类 中 实例 化 ThreadPoolExecutor 类 。 在 这 个 类 里 需要 做 以 下 事 : 
1. 为 线程 池 使 用 静态 变量 


为 了 有 一 个 单一 控制 点 用 来 限制 CPU 或 涉及 网 络 资源 的 Runnable 类 型 ， 你 可 能 需要 有 一 个 能 
管理 所 有 线程 的 线程 池 ， 且 每 个 线程 都 会 是 单个 实例 。 比 如 ， 你 可 以 把 这 个 作为 一 部 分 添加 
到 你 的 全 局 变量 的 声明 中 去 : 


public class PhotoManager { 
static { 


// Creates a single static instance of PhotoManager 
sInstance - new PhotoManager(); 


2. 使 用 私有 构造 方法 


让 构造 方法 私有 从 而 保证 这 是 一 个 单 例 ， 这 意味 着 你 不 需要 在 同步 代码 块 (Synchronized 
block) 中 额外 访问 这 个 类 : 


public class PhotoManager { 
JEE 
* Constructs the work queues and thread pools used to download 


* and decode images. Because the constructor is marked private, 


* it's unavailable to other classes, even in the same package. 
i 
private PhotoManager() { 


3. 通 过 调用 线程 池 类 里 的 方法 开启 你 的 任务 


在 线程 池 类 中 定义 一 个 能 添加 任务 到 线程 池 队 列 的 方法 。 例 如 : 


public class PhotoManager { 


// Called by the PhotoView to get a photo 
static public PhotoTask startDownload( 
PhotoView imageView, 
boolean cacheFlag) { 


// Adds a download task to the thread pool for execution 
sInstance. 


mDownloadThreadPool. 
execute(downloadTask.getHTTPDownloadRunnable()); 


4. 在 构造 方法 中 实例 化 一 个 Handler， 且 将 它 附 加 到 你 APP 的 UI 线程 。 


一 个 Handler 允 许 你 的 APP 安 全 地 调用 UI 对 象 ( 例 如 View 对 象 ) 的 方法 。 大 多 数 UI 对 象 只 能 从 
UI 线程 安全 的 代码 中 被 修改 。 这 个 方法 将 会 在 与 UI 线程 进行 通信 (Communicate with the UI 
Thread) 这 一 课 中 进行 详细 的 描述 。 例 如 : 


private PhotoManager() { 


// Defines a Handler object that's attached to the UI thread 
mHandler = new Handler(Looper.getMainLooper()) { 
= 
* handleMessage() defines the operations to perform when 
* the Handler receives a new Message to process. 
eh 
@Override 
public void handleMessage(Message inputMessage) { 


确定 线程 池 的 参数 


一 理 有 了 整体 的 类 结构 ,你 可 以 开始 定义 线程 池 了 。 为 了 初始 化 一 个 ThreadPoolExecutor 对 
象 ， 你 需要 提供 以 下 数值 : 


1. 线程 池 的 初始 化 大 小 和 最 大 的 大 小 


这 个 是 指 最 初 分 配给 线程 池 的 线程 数量 ， 以 及 线程 池 中 允许 的 最 大 线程 数量 。 在 线程 池 中 拥 
有 的 线程 数量 主要 取决 于 你 的 设备 的 CPU 内核 数 。 


这 个 数字 可 以 从 系统 环境 中 获得 : 


public class PhotoManager { 


/* 
* Gets the number of available cores 
* (not always the same as the maximum number of cores) 
27 
private static int NUMBER OF CORES - 
Runtime.getRuntime().availableProcessors(); 


这 个 数字 可 能 并 不 反映 设备 的 物理 核心 数量 ， 因 为 一 些 设备 根据 系统 负载 关闭 了 一 个 或 多 个 
CPU 内 核 ， 对 于 这 样 的 设备 ， availableProcessors() 方法 返回 的 是 处 于 活动 状态 的 内 核 数 

量 ， 可 能 少 于 设备 的 实际 内 核 总 数 。 

2. 线 程 保持 活动 状态 的 持续 时 间 和 时 间 单 位 

这 个 是 指 线程 被 关闭 前 保持 空闲 状态 的 持续 时 间 。 这 个 持续 时 间 通 过 时 间 单 位 值 进 行 解 译 ， 
是 TimeUnit() 中 定义 的 常量 之 一 。 


3. 一 个 任务 队列 


这 个 传 入 的 队列 由 ThreadPoolExecutor 获 取 的 Runnable 对 象 组 成 。 为 了 执行 一 个 线程 中 的 代 
码 ， 一 个 线程 池 管理 者 从 先进 先 出 的 队列 中 取出 一 个 Runnable 对 象 且 把 它 附加 到 一 个 线程 。 
娄 你 创建 线程 池 时 需要 提供 一 个 队列 对 象 ， 这 个 队列 对 象 类 必须 实现 BlockingQueue 接 口 。 为 
了 满足 你 的 APP 的 需求 ， 你 可 以 选择 一 个 Android SDK 中 已 经 存在 的 队列 实现 类 。 为 了 学 习 更 
多 相关 的 知识 ， 你 可 以 看 一 下 ThreadPoolExecutor 类 的 概述 。 下 面 是 一 个 使 

用 LinkedBlockingQueue 实 现 的 例子 : 


public class PhotoManager { 
private PhotoManager() { 


// A queue of Runnables 
private final BlockingQueue<Runnable> mDecodeWorkQueue; 


// Instantiates the queue of Runnables as a LinkedBlockingQueue 
mDecodeWorkQueue = new LinkedBlockingQueue<Runnable>(); 


创建 一 个 线程 池 


为 了 创建 一 个 线程 池 ， 可 以 通过 调用 ThreadPoolExecutor() 构 造 方法 初始 化 一 个 线程 池 管 理 者 
对 象 ， 这 样 就 能 创建 和 管理 一 组 可 约束 的 线程 了 。 如 果 线 程 池 的 初始 化 大 小 和 最 大 大 小 相 
同 ，ThreadPoolExecutor 在 实例 化 的 时 候 就 会 创建 所 有 的 线程 对 象 。 例 如 : 


private PhotoManager() { 


// Sets the amount of time an idle thread waits before terminating 
private static final int KEEP ALIVE TIME - 1; 
// Sets the Time Unit to seconds 
private static final TimeUnit KEEP ALIVE TIME UNIT - TimeUnit.SECONDS; 
// Creates a thread pool manager 
mDecodeThreadPool - new ThreadPoolExecutor( 

NUMBER OF CORES, // Initial pool size 

NUMBER OF CORES, // Max pool size 

KEEP ALIVE TIME, 

KEEP ALIVE TIME UNIT, 

mDecodeWorkQueue); 


为 多 线程 创建 线程 池 
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启动 与 停止 线程 池 中 的 线程 


编写 :AllenZheng1991 - 原文 :http://developer.android.com/training/multiple-threads/run- 
code.html 


在 前 面 的 课程 中 向 你 展示 了 如 何 去 定 义 一 个 可 以 管理 线程 池 且 能 在 他 们 中 执行 任务 代码 的 
类 。 在 这 一 课 中 我 们 将 向 你 展示 如 何在 线程 池 中 执行 任务 代码 。 为 了 达到 这 个 目的 ， 你 需要 
把 任务 添加 到 线程 池 的 工作 队列 中 去 ， 当 一 个 线程 变 成 可 运行 状态 时 ，ThreadPoolExecutor 
从 工作 队列 中 取出 一 个 任务 ， 然 后 在 该 线程 中 执行 。 


这 节 课 同时 也 向 你 展示 了 如 何 去 停 止 一 个 正在 执行 的 任务 ， 这 个 任务 可 能 在 刚 开 始 执行 时 是 
你 想 要 的 ， 但 后 来 发 现 它 所 做 的 工作 并 不 是 你 所 需要 的 。 你 可 以 取消 线程 正在 执行 的 任务 ， 
而 不 是 浪费 处 理 器 的 运行 时 间 。 例 如 你 正在 从 网 络 上 下 载 图 片 且 对 下 载 的 图 片 进行 了 缓存 ， 
当 检 测 到 正在 下 载 的 图 片 在 缓存 中 已 经 存在 时 ， 你 可 能 希望 停止 这 个 下 载 任务 。 当 然 ， 这 取 
决 于 你 编写 APP 的 方式 ， 因 为 可 能 压 在 你 启动 下 载 任务 之 前 无 法 获知 是 否 需要 启动 这 个 任 


务 。 


尼 动 线程 池 中 的 线程 执行 任务 


为 了 在 一 个 特定 的 线程 池 的 线程 里 开启 一 个 任务 ， 可 以 通过 调用 
ThreadPoolExecutor.execute()， 它 需要 提供 一 个 Runnable 类 型 的 参数 ， 这 个 调用 会 把 该 任务 
添加 到 这 个 线程 池 中 的 工作 队列 。 当 一 个 空闲 的 线程 进入 可 执行 状态 时 ， 线 程 管理 者 从 工作 
队列 中 取出 等 待 时 间 最 长 的 那个 任务 ， 并 且 在 线程 中 执行 它 。 


public class PhotoManager { 
public void handleState(PhotoTask photoTask, int state) { 
switch (state) { 

// The task finished downloading the image 

case DOWNLOAD COMPLETE: 

// Decodes the image 

mDecodeThreadPool.execute( 
photoTask.getPhotoDecodeRunnable()); 


当 ThreadPoolExecutor 在 一 个 线程 中 开启 一 个 Runnable 后 ， 它 会 自动 调用 Runnable 的 run() 方 
法 。 


中 断 正 在 执行 的 代码 


为 了 停止 执行 一 个 任务 ， 你 必须 中 断 执 行 这 个 任务 的 线程 。 在 准备 做 这 件 事 之 前 ， 当 你 创建 
一 个 任务 时 ， 你 需要 存储 处 理 该 任务 的 线程 。 例 如 : 


class PhotoDecodeRunnable implements Runnable { 
// Defines the code to run for this task 
public void run() { 
fs 
* Stores the current Thread in the 





* object that contains PhotoDecodeRunnable 
2 
mPhotoTask.setImageDecodeThread(Thread.currentThread()); 


想 要 中 断 一 个 线程 ， 你 可 以 调用 Thread.interrupt())。 需 要 注意 的 是 这 些 线程 对 象 都 被 系统 控 
制 ， 系 统 可 以 在 你 的 APP 进 程 之 外 修改 他 们 。 因 为 这 个 原因 ， 在 你 要 中 断 一 个 线程 时 ， 你 需 
要 把 这 段 代码 放 在 一 个 同步 代码 块 中 对 这 个 线程 的 访问 加 锁 来 解决 这 个 问题 。 例 如 : 


public class PhotoManager { 
public static void cancelAll() { 
/* 
* Creates an array of Runnables that's the same size as the 
* thread pool work queue 
gU 
Runnable[] runnableArray - new Runnable[mDecodeWorkQueue.size()]; 
// Populates the array with the Runnables in the queue 
mDecodeWorkQueue.toArray(runnableArray); 
// Stores the array length in order to iterate over the array 
int len - runnableArray.length; 
/* 
* Iterates over the array of Runnables and interrupts each one's Thread. 
i 
synchronized (sInstance) ( 
// Iterates over the array of tasks 
for (int runnableIndex = 0; runnableIndex < len; runnableIndex++) ( 
// Gets the current thread 
Thread thread - runnableArray[taskArrayIndex].mThread; 
// if the Thread exists, post an interrupt to it 
if (null != thread) { 
thread.interrupt(); 


在 大 多 数 情况 下 ， 通 过 调用 Thread.interrupt() 能 立即 中 断 这 个 线程 ， 然 而 他 只 能 停止 那些 处 于 
等 待 状态 的 线程 ， 却 不 能 中 断 那 些 占 据 CPU 或 者 耗 时 的 连接 网 络 的 任务 。 为 了 避免 拖 慢 系统 
速度 或 造成 系统 死 锁 ， 在 尝试 执行 耗 时 操作 之 前 ， 你 应 该 测试 当前 是 否 存在 处 于 挂 起 状态 的 
中 断 请 求 : 


ES 
* Before continuing, checks to see that the Thread hasn't 
* been interrupted 
iA 
if (Thread.interrupted()) { 
me unm 


// Decodes a byte array into a Bitmap (CPU-intensive) 
BitmapFactory.decodeByteArray( 
imageBuffer, 0, imageBuffer.length, bitmapOptions); 


启动 与 停止 线程 池 中 的 线程 
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与 UI 线程 通信 


编写 :AllenZheng1991 - Æ X :http://developer.android.com/training/multiple- 
threads/communicate-ui.html 


在 前 面 的 课程 中 你 学 习 了 如 何在 一 个 被 ThreadPoolExecutor 管 理 的 线程 中 开启 一 个 任务 。 最 
后 这 一 节 课 将 会 向 你 展示 如 何 从 执行 的 任务 中 发 送 数 据 给 运行 在 UI 线程 中 的 对 象 。 这 个 功能 
允许 你 的 任务 可 以 做 后 人 台 工 作 ， 然 后 把 得 到 的 结果 数据 转移 给 UI 元 素 使 用 ， 例 如 位 图 数据 。 


任何 一 个 APP 都 有 自己 特定 的 一 个 线程 用 来 运行 UI 对 象 ， 比 如 View 对 象 ， 这 个 线程 我 们 称 之 
为 UI 线程 。 只 有 运行 在 UI 线程 中 的 对 象 能 访问 运行 在 其 它 线 程 中 的 对 象 。 因 为 你 的 任务 执行 
的 线程 来 自 一 个 线程 池 而 不 是 执行 在 UI 线程 ， 所 以 他 们 不 能 访问 UI 对 象 。 为 了 把 数据 从 一 个 
后 台 线 程 转移 到 UI 线程 ， 需 要 使 用 一 个 运行 在 UI 线程 里 的 Handler。 


在 UI 线程 中 定义 一 个 Handler 


Handler 属 于 Android 系 统 的 线程 管理 框架 的 一 部 分 。 一 个 Handler 对 象 用 于 接收 消息 和 执行 处 
理 消息 的 代码 。 一 般 情 况 下 ， 如 果 你 为 一 个 新 线程 创建 了 一 个 Handler， 你 还 需要 创建 一 

个 Handler， 让 它 与 一 个 已 经 存在 的 线程 关联 ， 用 于 这 两 个 线程 之 间 的 通信 。 如 果 你 把 一 

个 Handler 关 联 到 UI 线程 ， 处 理 消 息 的 代码 就 会 在 UI 线程 中 执行 。 


你 可 以 在 一 个 用 于 创建 你 的 线程 池 的 类 的 构造 方法 中 实例 化 一 个 Handler 对 象 ， 并 把 它 定 义 为 
全 局 变量 ， 然 后 通过 使 用 Handler (Looper) 这 一 构造 方法 实例 化 它 ， 用 于 关联 到 UI 线 

程 。Handler(Looper) 这 一 构造 方法 需要 传 入 了 一 个 Looper 对 象 ， 它 是 Android 系 统 的 线程 管理 
框架 中 的 另 一 部 分 。 当 你 在 一 个 特定 的 Looper 实 例 的 基础 上 去 实例 化 一 个 Handler 时 ， 这 

个 Handler 与 Looper 和 运行 在 同一 个 线程 里 。 例 如 : 


private PhotoManager() { 


// Defines a Handler object that's attached to the UI thread 
mHandler = new Handler(Looper.getMainLooper()) { 


在 这 个 Handler 里 需要 重 写 handleMessage() 方 法 。 当 这 个 Handler 接 收 到 由 另外 一 个 线程 管理 
的 Handler 发 送 过 来 的 新 消息 时 ，Android 系 统 会 自动 调用 这 个 方法 ， 而 所 有 线程 对 应 的 
Handler 都 会 收 到 相同 信息 。 例 如 : 


/* 
* handleMessage() defines the operations to perform when 
* the Handler receives a new Message to process. 
d) 
@Override 
public void handleMessage(Message inputMessage) { 
// Gets the image task from the incoming Message object. 
PhotoTask photoTask = (PhotoTask) inputMessage.obj; 


下 一 部 分 将 向 你 展示 如 何 用 Handler 转 移 数据 。 


把 数据 从 一 个 任务 中 转移 到 UI 线程 


为 了 从 一 个 运行 在 后 台 线 程 的 任务 对 象 中 转移 数据 到 UI 线程 中 的 一 个 对 象 ， 首 先 需 要 存储 任 
务 对 象 中 的 数据 和 UI| 对 象 的 引用 ; 接 下 来 传递 任务 对 象 和 状态 码 给 实例 化 Handler 的 那个 对 
象 。 在 这 个 对 象 里 ， 发 送 一 个 包含 任务 对 象 和 状态 的 Message 给 Handler 也 运行 在 UI 线程 中 ， 
所 以 它 可 以 把 数据 转移 到 UI 线程 。 


在 任务 对 象 中 存储 数据 


比如 这 里 有 一 个 Runnable， 它 运行 在 一 个 编码 了 一 个 Bitmap 且 存储 这 个 Bitmap 到 父 
类 PhotoTasKk 对 象 里 的 后 台 线程 。 这 个 Runnable 同 样 也 存储 了 状态 
码 DECODE STATE COMPLETED 。 


// A class that decodes photo files into Bitmaps 
class PhotoDecodeRunnable implements Runnable { 


PhotoDecodeRunnable(PhotoTask downloadTask) { 
mPhotoTask - downloadTask; 


// Gets the downloaded byte array 
byte[] imageBuffer - mPhotoTask.getByteBuffer(); 


// Runs the code for this task 
public void run() { 


// Tries to decode the image buffer 
returnBitmap - BitmapFactory.decodeByteArray( 
imageBuffer, 
9, 
imageBuffer.length, 
bitmapOptions 
); 


// Sets the ImageView Bitmap 
mPhotoTask.setImage(returnBitmap); 

// Reports a status of "completed" 
mPhotoTask.handleDecodeState(DECODE STATE COMPLETED); 


PhotoTask 类 还 包含 一 个 用 于 显示 Bitmap 的 ImageView 的 引用 。 虽 然 Bitmap 和 
ImageViewlmageView</a> 的 引用 在 同一 个 对 象 中 ， 但 你 不 能 把 这 个 Bitmap 分 配给 ImageView 
去 显示 ， 因 为 它们 并 没有 运行 在 UI 线程 中 。 


这 时 ， 下 一 步 应 该 发 送 这 个 状态 给 photoTask 对 象 。 


发 送 状 态 取 决 于 对 人 象 层 


PholoTasKk 是 下 一 个 层次 更 高 的 对 象 ， 它 包含 将 要 展示 数据 的 编码 数据 和 View 对 象 的 引用 。 它 
会 收 到 一 个 来 自 PhotoDecodeRunnable 的 状态 码 ， 并 把 这 个 状态 码 单 独 传 递 到 一 个 包含 线程 
池 和 Handler 实 例 的 对 象 : 


public class PhotoTask ( 


// Gets a handle to the object that creates the thread pools 
sPhotoManager - PhotoManager.getInstance(); 


public void handleDecodeState(int state) { 
int outState; 


// Converts the decode state to the overall state. 
switch(state) ( 
case PhotoDecodeRunnable.DECODE STATE COMPLETED: 


outState - PhotoManager.TASK COMPLETE; 
break; 


} 


// Calls the generalized state method 
handleState(outState); 


// Passes the state to PhotoManager 
void handleState(int state) { 
US 
* Passes a handle to this task and the 
* current state to the class that created 
* the thread pools 
iA 
sPhotoManager.handleState(this, state); 


转移 数据 到 UI 


从 PhotoTask 对 象 那 里 ，PhotoManager 对 象 收 到 了 一 个 状态 码 和 一 个 PhotoTask 对 象 的 引用 。 
为 状态 码 是 TASK_COMPLETE， 所 以 创建 一 个 Message 应 该 包含 状态 和 任务 对 象 ， 然 后 把 
它 发 送 给 Handler : 





public class PhotoManager { 


// Handle status messages from tasks 
public void handleState(PhotoTask photoTask, int state) { 
switch (state) { 


// The task finished downloading and decoding the image 
case TASK COMPLETE: 
/* 
* Creates a message for the Handler 
* with the state and the task object 
iA 
Message completeMessage - 
mHandler.obtainMessage(state, photoTask); 
completeMessage.sendToTarget(); 
break; 


最 终 ，HandlerhandleMessage() 会 检查 每 个 传 入 进来 的 Message， 如 果 状 态 码 

X TASK COMPLETE ， 这 时 任务 就 完成 了 ， 而 传 入 的 Message 里 的 PhotoTask 对 象 里 同时 包 
含 一 个 Bitmap 和 一 个 ImageView。 因 为 Handler.handleMessage() 运 行 在 UI 线程 里 ， 所 以 它 能 
安全 地 转移 Bitmap 数 据 给 ImageView : 


private PhotoManager() { 


mHandler - new Handler(Looper.getMainLooper()) ( 
@Override 
public void handleMessage(Message inputMessage) { 
// Gets the task from the incoming Message object. 
PhotoTask photoTask = (PhotoTask) inputMessage.obj; 
// Gets the ImageView for this task 
PhotoView localView = photoTask.getPhotoView(); 


switch (inputMessage.what) { 


// The decoding is done 
case TASK_COMPLETE: 
P R2 
* Moves the Bitmap from the task 
* to the View 
A 
localView.setImageBitmap(photoTask.getImage()); 
break; 
default: 
FE 
* Pass along other messages from the UI 
Wi 
super.handleMessage(inputMessage); 


避免 出 现 程序 无 响应 ANR(Keeping Your App 
Responsive) 


^h 5 :Kesenhoo - /$. X :http://developer.android.com/training/articles/perf-anr.html 


可 能 你 写 的 代码 在 性 能 测试 上 表现 良好 ， 但 是 你 的 应 用 仍然 有 时 候 会 反应 迟缓 (sluggish)， 停 
顿 (hang) 或 者 长 时 间 卡 死 (frezze)， 或 者 是 应 用 处 理 输入 的 数据 花费 时 间 过 长 。 对 于 你 的 应 用 
来 说 最 模 糕 的 事情 是 出 现 " 程 序 无 响应 (Application Not Responding)" (ANR) 的 警示 框 。 


在 Android 中 ， 系 统 通过 显示 ANR 人 警示 框 来 保护 程序 的 长 时 间 无 响应 。 对 话 框 如 下 : 


Hello World isn't responding. 


Do you want to close it? 


Wait OK 





此 时 ， 你 的 应 用 已 经 经 历 过 一 段 时 间 的 无 法 响应 了 ， 因 此 系统 提供 用 户 可 以 退出 应 用 的 选 
择 。 为 你 的 程序 提供 良好 的 响应 性 是 至 关 重 要 的 ， 这 样 才 能 够 避免 系统 为 用 户 显示 ANR 的 警 
示 框 。 


这 节 课 描述 了 Android 系 统 是 如 何 判 断 一 个 应 用 不 可 响应 的 。 这 节 课 还 会 提供 程序 编写 的 指导 
原则 ， 确 保 你 的 程序 保持 响应 性 。 


是 什么 导致 了 ANR?(What Triggers ANR?) 


通常 来 说 ， 系 统 会 在 程序 无 法 响应 用 户 的 输入 事件 时 显示 ANR。 例 如 ， 如 果 一 个 程序 在 UI 线 
程 执行 JO 操 作 ( 通 常 是 网 络 请 求 或 者 是 文件 读 写 )， 这 样 系统 就 无 法 处 理 用 户 的 输入 事件 。 或 
者 是 应 用 在 UI 线程 花费 了 太 多 的 时 间 用 来 建立 一 个 复杂 的 在 内 存 中 的 数据 结构 ， 又 或 者 是 在 
一 个 游戏 程序 的 U 线 程 中 执行 了 一 个 复杂 耗 时 的 计算 移动 的 操作 。 确 保 那 些 计算 操作 高 效 是 
很 重要 的 ， 不 过 即使 是 最 高 效 的 代码 也 是 需要 花 时 间 执 行 的 。 


对 于 你 的 应 用 中 任何 可 能 长 时 间 执 行 的 操作 ， 你 都 不 应 该 执行 在 UI 线程 。 你 可 以 创建 一 个 工 
作 线 程 ， 把 那些 操作 都 执行 在 工作 线程 中 。 这 确保 了 UI 线程 (这 个 线程 会 负责 处 理 Ul 事 件 ) 能 
够 顺利 执行 ， 也 预防 了 系统 因 代 码 僵 死 而 崩溃 。 因 为 Ul 线 程 是 和 类 级 别 相关 联 的 ， 你 可 以 把 
相应 性 作为 一 个 类 级 别 (class-level) 的 问题 ( 相 比 来 说 ， 代 码 性 能 则 属于 方法 级 别 (method- 
level) 的 问题 ) 


在 Android 中 ， 程 序 的 响应 性 是 由 Activity Manager 与 Window Manager 系 统 服 务 来 负责 监控 
的 。 当 系统 监测 到 下 面 的 条 件 之 一 时 会 显示 ANR 的 对 话 框 : 


。 对 输入 事件 (例如 硬件 点 击 或 者 屏幕 触摸 事件 )，5 秒 内 都 无 响应 。 
e BroadReceiver 不 能 够 在 10 秒 内 结束 接收 到 任务 


如 何 避 免 ANRs(How to Avoid ANRs) 


Android 程 序 通常 是 执行 在 默认 的 UI 线程 (也 就 是 main 线 程 ) 中 的 。 这 意味 着 在 UI 线程 中 执行 的 
任何 长 时 间 的 操作 都 可 能 触发 ANR， 因 为 程序 没有 给 自己 处 理 输 BS d cus Ed 
机 会 。 


因此 ， 任 何 执 行 在 UI 线程 的 方法 都 应 该 尽 可 能 的 简短 快速 。 特 别 是 ， 在 activity 的 生命 周期 的 
关键 方法 oncreate() 与 onResume() 方法 中 应 该 尽 可 能 的 做 比较 少 的 事情 。 类 似 网 络 或 者 DB 
操作 等 可 能 长 时 间 执 行 的 操作 ， AE AA E A E REN 间 计 算 的 操作 ， 都 应 
该 执行 在 工作 线程 中 。( 在 DB 操作 中 ， 可 以 通过 弄 步 的 网 络 请 求 )。 


为 了 执行 一 个 长 时 间 的 耗 时 操作 而 创建 一 个 工作 线程 最 方便 高 效 的 方式 是 使 用 AsyncTask ° 

只 需要 继承 AsyncTask 并 实现 doInBackground() das AR RU 为 了 把 任务 执行 的 进度 
呈现 给 用 户 ， 你 可 以 执行 publishprogress() 方法 ， 这 个 方法 会 触发 Ha QN 的 回 

调 方法 。 在 onProgressupdate() 的 回调 方法 中 ( 它 执行 在 UI 线程 )， 你 可 以 执行 通知 用 户 进 度 的 

操作 ， 例 如 


private class DownloadFilesTask extends AsyncTask<URL, Integer, Long> { 
// Do the long-running work in here 
protected Long doInBackground(URL... urls) { 
int count = urls.length; 
long totalSize = 0; 
for (int i = 0; i < count; i++) { 
totalSize += Downloader .downloadFile(urls[i]); 
publishProgress((int) ((i / (float) count) * 100)); 
// Escape early if cancel is called 
if (isCancelled()) break; 
} 


return totalSize; 


} 


// This is called each time you call publishProgress() 
protected void onProgressUpdate(Integer... progress) { 
setProgressPercent(progress[0]); 


} 


// This is called when doInBackground() is finished 
protected void onPostExecute(Long result) { 
showNotification("Downloaded " + result + " bytes"); 


} 


为 了 能 够 执行 这 个 工作 线程 ， 只 需要 创建 一 个 实例 并 执行 execute() : 


new DownloadFilesTask().execute(urli, url2, ur13); 


相 比 起 AsycnTask 来 说 ， 创 建 自 己 的 线程 或 者 HandlerThread 稍 微 复杂 一 点 。 如 果 你 想 这 样 
做 ， 你 应 该 通过 Process.setThreadPriority() 并 传递 THREAD_PRIORITY_BACKGROUND 来 设置 线程 
的 优先 级 为 "background"。 如 果 你 不 通过 这 个 方式 来 给 线程 设置 一 个 低 的 优先 级 ， 那 么 这 个 
线程 仍然 会 使 得 你 的 应 用 显得 卡 顿 ， 因 为 这 个 线程 默认 与 UI 线程 有 着 同样 的 优先 级 。 


如 果 你 实现 了 Thread 或 者 HandlerThread， 请 确保 你 的 UI 线程 不 会 因为 等 待 工 作 线 程 的 某 个 任 
务 而 去 执行 Thread.wait() 或 者 Thread.sleep()。UI 线 程 不 应 该 去 等 待 工作 线程 完成 某 个 任务 ， 
你 的 UI 线程 应 该 提供 一 个 Handler 给 其 他 工作 线程 ， 这 样 工 作 线 程 能 够 通过 这 个 Handler 在 任 
务 结束 的 时 候 通 知 UI 线程 。 使 用 这 样 的 方式 来 设计 你 的 应 用 程序 可 以 使 得 你 的 程序 UI 线程 保 
持 响 应 性 ， 以 此 来 避免 ANR。 


BroadcastReceiver 有 特定 执行 时 间 的 限制 说 明了 broadcast receivers 应 该 做 的 是 : 简短 快速 
的 任务 ， 避 免 执 行 费时 的 操作 ， 例 如 保存 数据 或 者 注册 一 个 Notification。 正 如 在 UI 线程 中 执 
行 的 方法 一 样 ， 程 序 应 该 避免 在 broadcast receiver 中 执行 费时 的 长 任务 。 但 不 是 采用 通过 工 
作 线 程 来 执行 复杂 的 任务 的 方式 ， 你 的 程序 应 该 启动 一 个 IntentService 来 响应 intent 
broadcast 的 长 时 间 任 务 。 


Tip: 你 可 以 使 用 StrictMode 来 帮助 寻找 因为 不 小 心 加 入 到 UI 线程 的 潜在 的 长 时 间 执 行 的 
操作 ， 例 如 网 络 或 者 DB 相关 的 任务 。 


增加 响应 性 (Reinforce Responsiveness) 


通常 来 说 ，100ms - 200ms 是 用 户 能 够 察觉 到 卡 顿 的 上 限 。 这 样 的 话 ， 下 面 有 一 些 避 免 ANR 
的 技巧 : 


o 如 果 你 的 程序 需要 响应 正在 后 人 台 加 载 的 任务 ， 在 你 的 Ul 中 可 以 显示 ProgressBar 来 显示 进 
度 。 

e 对 游戏 程序 ， 在 工作 线程 执行 计算 的 任务 。 

e 如 果 你 的 程序 在 启动 阶段 有 一 个 耗 时 的 初始 化 操作 ， 可 以 考虑 显示 一 个 闪 屏 ， 要 么 尽快 
的 显示 主 界面 ， 然 后 马上 显示 一 个 加 载 的 对 话 框 ， 异 步 加 载 数据 。 无 论 哪 种 情况 ， 你 都 
应 该 显示 一 个 进度 信息 ， 以 免 用 户 感觉 程序 有 卡 顿 的 情况 。 

o 使 用 性 能 测试 工具 ， 例 如 Systrace 与 Traceview 来 判断 程序 中 影响 响应 性 的 瓶颈 。 


JNI Tips 


编写 :pedant - 原文 :http://developer.android.com/training/articles/perf-jni.html 


JNI 全 称 Java Native Interface。 它 为 托管 代码 (使 用 Java 编 程 语言 编写 ) 与 本 地 代码 (使 用 
C/C++ 编写 ) 提供 了 一 种 交互 方式 。 它 是 与 厂商 无 关 的 (vendor-neutral) ,支持 从 动态 共享 库 
中 加 载 代 码 ， 虽 然 这 样 会 稍 显 麻烦 ， 但 有 时 这 是 相当 有 效 的 。 


如 果 你 对 JNI| 还 不 是 大 熟悉 ， 可 以 先 通读 Java Native Interface Specification 这 篇 文章 来 对 JNI 
如 何 工作 以 及 哪些 特性 可 用 有 个 大 致 的 印象 。 这 种 接口 的 一 些 方面 不 能 立即 一 读 就 显 而 多 
见 ， 所 以 你 会 发 现 接 下 来 的 几 个 章节 很 有 用 处 。 


JavaVM 及 JNIEnv 


JNI 定 义 了 两 种 关键 数据 结构 ，“JavaVM”" 和 “JNIEnv”。 它 们 本 质 上 都 是 指向 函数 表 指 针 的 指针 

(在 C+t+ 版 本 中 ， 它 们 被 定义 为 类 ， 该 类 包含 一 个 指向 函数 表 的 指针 ， 以 及 一 系列 可 以 通过 这 
个 函数 表 间 接地 访问 对 应 的 JNI| 函 数 的 成 员 函 数 ) 。JavaVM 提 供 “ 调 用 接口 (invocation 
interface) "函数 , 允许 你 创建 和 销毁 一 个 JavaVM。 理 论 上 你 可 以 在 一 个 进程 中 拥有 多 个 
JavaVM 对 象 ， 但 安 车 只 允许 一 个 。 


JNIEnv 提 供 了 大 部 分 JNI 功 能 。 你 定义 的 所 有 本 地 函数 都 会 接收 JNIEnv 作 为 第 一 个 参数 。 


JNIEnv 是 用 作 线 程 局 部 存储 。 因 此 ， 你 不 能 在 线程 间 共 享 一 个 JNIEnv 变 量 。 如 果 在 一 段 代码 
中 没有 其 它 办 法 获得 它 的 JNIEnv， 你 可 以 共享 JavaVM 对 象 ， 使 用 GetEnv 来 取得 该 线程 下 的 
JNIEnv (如 果 该 线程 有 一 个 JavaVM 的 话 ; 见 下 面 的 AttachCurrentThread) ° 


JNIEnv 和 JavaVM 的 在 C 声 明 是 不 同 于 在 C++ 的 声明 。 头 文件 jni.h" 根 据 它 是 以 C 还 是 以 C++ 模 
式 包含 来 提供 不 同 的 类 型 定义 (typedefs) 。 因 此 ， 不 建议 把 JNIEnv 参 数 放 到 可 能 被 两 种 语 
言 引 入 的 头 文件 中 ( 换 一 句 话 说 : 如 果 你 的 头 文 件 需 要 #ifdef — cplusplus， 你 可 能 不 得 不 在 
任何 涉及 到 JNIEnv 的 内 容 处 都 要 做 些 额 外 的 工作 ) 。 


线程 


所 有 的 线程 都 是 Linux 线 程 ， 由 内 核 统一 调度 。 它 们 通常 从 托管 代码 中 启动 (使 用 
Thread.start) ， 但 它们 也 能 够 在 其 他 任何 地 方 创建 ， 然 后 连接 (attach) $lJavaVM » 例如， 
一 个 用 pthread _ create 局 动 的 线程 能 够 使 用 JNI AttachCurrentThread 或 
AttachCurrentThreadAsDaemon 了 有 函数 连接 到 JavaVM。 在 一 个 线程 成 功 连接 (attach) 之 前 ， 
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连接 一 个 本 地 环境 创建 的 线程 会 触发 构造 一 个 java.lang.Thread 对 象 ， 然 后 其 被 添加 到 主线 程 
群 组 (main ThreadGroup) ,以 让 调试 器 可 以 探测 到 。 对 一 个 已 经 连接 的 线程 使 用 
AttachCurrentThread 不 做 任何 操作 (no-op) ° 


安 卓 不 能 中 止 正在 执行 本 地 代码 的 线程 。 如 果 正 在 进行 垃圾 回收 ， 或 者 调试 器 已 发 出 了 中 止 
请 求 ， 安 卓 会 在 下 一 次 调用 JNI 函 数 的 时 候 中 止 线程 。 


连接 过 的 (attached) 线程 在 它们 退出 之 前 必须 通过 JNI 调 用 DetachCurrentThread。 如 果 你 
觉得 直接 这 样 编写 不 大 优雅 ， 在 安 卓 2.0 (Eclair) 及 以 上 ， 你 可 以 使 用 pthread key. create 
来 定义 一 个 析 构 函数 ， 它 将 会 在 线程 退出 时 被 调用 ， 你 可 以 在 那儿 调用 DetachCurrentThread 

(使 用 生成 的 key 与 pthread_setspecific 将 JNIEnv 存 储 到 线程 局 部 空间 内 ; 这 样 JNIEnv 能 够 作 
为 参数 传 入 到 析 构 函数 当中 去 ) © 


jclass, jmethodlD, jfieldID 


如 果 你 想 在 本 地 代码 中 访问 一 个 对 象 的 字段 (field) ,你 可 以 像 下 面 这 样 做 : 


e 对 于 类 ， 使 用 FindClass 获 得 类 对 象 的 引用 
e 对 于 字段 ， 使 用 GetFieldld 获 得 字段 ID 
e 使 用 对 应 的 方法 (例如 GetintField) 获取 字段 下 面 的 值 


类 似 地 ， 要 调用 一 个 方法 ， 你 首先 得 获得 一 个 类 对 象 的 引用 ， 然 后 是 方法 ID (method ID). ° 
这 些 |D 通 常 是 指向 运行 时 内 部 数据 结构 。 查 找到 它们 需要 些 字符 串 比 较 ， 但 一 旦 你 实际 去 执 
了 它们 获得 字段 或 者 做 方法 调用 是 非常 快 的 。 


D k 


如 果 性 能 是 你 看 重 的 ， 那 么 一 旦 查找 出 这 些 值 之 后 在 你 的 本 地 代码 中 缓存 这 些 结果 是 非常 有 
用 的 。 因 为 每 个 进程 当中 的 JavaVM 是 存在 限制 的 ， 存 储 这 些 数据 到 本 地 静态 数据 结构 中 是 非 
常 合理 的 。 


类 引用 (class reference) ， 字 段 ID (field ID) 以 及 方法 ID (method ID) 在 类 被 卸载 前 都 是 
有 效 的 。 如 果 与 一 个 类 加 载 器 (ClassLoader) 相关 的 所 有 类 都 能 够 被 垃圾 回收 ， 但 是 这 种 情 
况 在 安 卓 上 是 罕见 其 至 不 可 能 出 现 ， 只 有 这 时 类 才 被 印 载 。 注 意 虽 然 jclass 是 一 个 类 引用 ， 但 
是 必须 要 调用 NewGlobalRef 保 护 起 来 ( 见 下 个 章节 ) 。 


当 一 个 类 被 加 载 时 如 果 你 想 缓 存 些 ID， 而 后 当 这 个 类 被 务 载 后 再 次 载 入 时 能 够 自动 地 更 新 这 
些 缓存 ID， 正 确 做 法 是 在 对 应 的 类 中 添加 一 段 像 下 面 的 代码 来 初始 化 这 些 ID : 


趣 的 class/field/method ID 





private static native void nativeInit(); 


static { 
nativeInit(); 


} 


在 你 的 C/C++ 代码 中 创建 一 个 nativeClasslnit 方 法 以 完成 ID 查 找 的 工作 。 当 这 个 类 被 初始 化 时 
这 段 代码 将 会 执行 一 次 。 当 这 个 类 被 卸载 后 而 后 再 次 载 入 时 ， 这 段 代码 将 会 再 次 执行 。 


局 部 和 全 局 引用 


每 个 传 入 本 地 方法 的 参数 ， 以 及 大 部 分 JNI 函 数 返 回 的 每 个 对 象 都 是 “局 部 引用 ”。 这 意味 着 它 
只 在 当前 线程 的 当前 方法 执行 期 间 有 效 。 即 使 这 个 对 象 本 身 在 本 地 方法 返回 之 后 仍然 存在 ， 
这 个 引用 也 是 无 效 的 。 


这 同样 适用 于 所 有 jobject 的 子 类 ， 包 括 jclass ，jstring， 以 及 jarray ( 当 JNI 扩 展 检查 是 打开 的 
时 候 ， 运 行 时 会 警告 你 对 大 部 分 对 象 引 用 的 误 用 ) © 


果 你 想 持 有 一 个 引用 更 长 的 时 间 ， 你 就 必须 使 用 一 个 全 局 ("global") 引用 了 。 
NewGlobalRef 部 数 以 一 个 局 部 引用 作为 参数 并 且 返 回 一 个 全 局 引用 。 全 局 引用 能 够 保证 在 你 
调用 DeleteGlobalRef 前 都 是 有 效 的 。 


这 种 模式 通常 被 用 在 缓存 一 个 从 FindClass 返 回 的 jclass 对 象 的 时 候 ， 例 如 


jclass localClass = env->FindClass("MyClass"); 
jclass globalClass = reinterpret_cast<jclass>(env->NewGlobalRef(localClass) ); 


所 有 的 JNI 方 法 都 接收 局 部 引用 和 全 局 引用 作为 参数 。 相 同 对 象 的 引用 却 可 能 具有 不 同 的 值 。 

例如 ， 用 相同 对 象 连续 地 调用 NewGlobalRef 得 到 返回 值 可 能 是 不 同 的 。 为 了 检查 两 个 引用 是 
否 指向 的 是 同一 个 对 象 ， 你 必须 使 用 IsSSameObject 函 数 。 绝 不 要 在 本 地 代码 中 用 == 符 号 来 比 
较 两 个 引用 。 


得 出 的 结论 就 是 你 绝 不 要 在 本 地 代码 中 假定 对 象 的 引用 是 常量 或 者 是 唯一 的 。 代 表 一 个 对 象 
ee s EE 有 不 同 的 值 。 在 连续 的 调用 过 程 中 两 个 不 同 的 
对 象 却 可 能 拥有 相同 的 32 位 值 。 不 要 使 用 jobject 的 值 作为 key. 


开发 者 需要 “不 过 度 分 配 ” 局 部 引用 。 在 实际 操作 中 这 意味 着 如 果 你 正在 创建 大 量 的 局 部 引用 ， 
或 许 是 通过 对 象 数 组 ， 你 应 该 使 用 DeleteLocalRef 手 动 地 释放 它们 ， 而 不 是 寄 希 望 JNI 来 为 你 
做 这 些 。 实 现 上 只 预 留 了 16 个 局 部 引用 的 空间 ， 所 以 如 果 你 需要 更 多 ， 要 么 你 删 掉 以 前 的 ， 
要 么 使 用 EnsureLocalCapacity/PushLocalFrame 来 预 留 更 多 。 


注意 jfieldID 和 jmethodID 是 映射 类 型 (opaque types) ， 不 是 对 象 引 用 ， 不 应 该 被 传 入 到 
NewGlobalRef 。 原 始 数据 指针 ， 像 GetStringUTFChars 和 GetByteArrayElements 的 返回 值 ， 
也 都 不 是 对 象 【( 它们 能 够 在 线程 间 传 递 ， 并 且 在 调用 对 应 的 Release 兄 数 之 前 都 是 有 效 的 ) 。 


还 有 一 种 不 常见 的 情况 值得 一 提 ， 如 果 你 使 用 AttachCurrentThread 连 接 (attach) 了 本 地 进 
程 ， 正 在 运行 的 代码 在 线程 分 离 (detach) 之 前 决 不 会 自动 释放 局 部 引用 。 你 创建 的 任何 局 
部 引用 必须 手动 删除 。 通 常 ， 任 何在 循环 中 创建 局 部 引用 的 本 地 代码 可 能 都 需要 做 一 些 手动 
删除 。 


UTF-8 ` UTF-16 字符 串 


Java 编 程 语言 使 用 UTF-16 格 式 。 为 了 便利 ，JNI 也 提供 了 支持 变形 UTF-8 (Modified UTF-8) 
的 方法 。 这 种 变形 编码 对 于 C 代 码 是 非常 有 用 的 ， 因 为 它 将 \U0000 编 码 成 0xc0 0x80， 而 不 是 
0x00。 最 怪 意 的 事情 是 你 能 在 具有 C 风 格 的 以 \0 结 束 的 字符 串 上 计数 ， 同 时 兼容 标准 的 libc 字 
符 串 函数 。 不 好 的 一 面 是 你 不 能 传 入 随意 的 UTF-8 数 据 到 JNI 函 数 而 还 指望 它 正常 工作 。 


如 果 可 能 的 话 ， 直 接 操作 UTF-16 字 符 串 通常 更 快 些 。 安 车 当 前 在 调用 GetStringChars 时 不 需 
要 拷贝 ， 而 GetStringUTFChars 需 要 一 次 分 配 并 且 转 换 为 UTF-8 格 式 。 注 意 UTF-16 字 符 串 不 
是 以 零 终 止 字符 串 ，\u0000 是 被 允许 的 ， 所 以 你 需要 像 对 jchar 指 针 一 样 地 处 理 字 符 串 的 长 
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型 的 C 格 式 的 指针 而 不 是 局 部 引用 。 它 们 在 Release 调 用 之 前 都 保证 有 效 ， 这 意味 着 当 本 地 方 
法 返回 时 它们 并 不 主动 释放 。 


传 入 NewStringUTF 有 函数 的 数据 必须 是 变形 UTF-8 格 式 。 一 种 常见 的 错误 情况 是 ， 从 文件 或 者 
网 络 流 中 读 取出 的 字符 数据 ， 没 有 过 滤 直 接 使 用 NewStringUTF 处 理 。 除 非 你 确定 数据 是 7 位 
的 ASCII 格 式 ， 否 则 你 需要 剔除 超出 7 位 ASCII 编 码 范 围 (high-ASCII) 的 字符 或 者 将 它们 转换 
为 对 应 的 变形 UTF-8 格 式 。 如 果 你 没 那样 做 ，UTF-16 的 转换 结果 可 能 不 会 是 你 想 要 的 结果 。 
JNI 扩 展 检查 将 会 扫描 字符 串 ， 然 后 警告 你 那些 无 效 的 数据 ， 但 是 它们 将 不 会 发 现 所 有 潜在 的 
风险 。 


JNI 提 供 了 一 系列 函数 来 访问 数组 对 象 中 的 内 容 。 对 象 数组 的 访问 只 能 一 次 一 条 ， 但 如 果 原 生 
类 型 数组 以 C 方 式 声明 ， 则 能 够 直接 进行 读 写 。 


为 了 让 接口 更 有 效率 而 不 受 VM 实 现 的 制约 ，GetArrayElements 系 列 调用 允许 运行 时 返回 一 个 
指向 实际 元 素 的 指针 ， 或 者 是 分 配 些 内 存 然后 拷贝 一 份 。 不 论 哪 种 方式 ， 返 回 的 原始 指针 在 

相应 的 Release 调 用 之 前 都 保证 有 效 (这 意味 着 ， 如 果 数 据 没 被 拷贝 ， 实 际 的 数组 对 象 将 会 受 
到 牵制 ， 不 能 重新 成 为 整理 堆 空间 的 一 部 分 ) 。 你 必须 释放 (Release) 每 个 你 通过 Get 得 到 
的 数组 。 同 时 ， 如 果 Get 调 用 失败 ， 你 必须 确保 你 的 代码 在 之 后 不 会 去 尝试 调用 Release 来 释 
放 一 个 空 指针 (NULL pointer) ° 


你 可 以 用 一 个 非 空 指针 作为 IsCopy 参 数 的 值 来 决定 数据 是 否 会 被 拷贝 。 这 相当 有 用 。 


Release 类 的 函数 接收 一 个 mode 参 数 ， 这 个 参数 的 值 可 选 的 有 下 面 三 种 。 而 运行 时 具体 执行 
的 操作 取决 于 它 返 回 的 指针 是 指向 丨 实数 据 还 是 拷贝 出 来 的 那 份 。 


° 0 
o ALA: 实际 数组 对 象 不 受到 牵制 
o 拷贝 的 : 数据 将 会 复制 回去 ， 备 份 空间 将 会 被 释放 。 
e JNI COMMIT 
o Š EAJ: 不 做 任何 操作 
o 拷贝 的 : 数据 将 会 复制 回去 ， 备 份 空间 将 不 会 被 释放 。 
e JNI ABORT 
o ALA: 实际 数组 对 象 不 受到 牵制 .之 前 的 写 入 不 会 被 取消 。 
o 拷贝 的 : 备份 空间 将 会 被 释放 ; 里 面 所 有 的 变更 都 会 丢失 。 


检查 isCopy 标 识 的 一 个 原因 是 对 一 个 数组 做 出 变更 后 确认 你 是 否 需 要 传 入 JNI COMMIT 来 调 
用 Release 兄 数 。 如 果 你 交 蔡 地 执行 变更 和 读 取 数组 内 容 的 代码 ， 你 也 许可 以 跳 过 无 操作 
(no-op) 的 JNI_COMMIT。 检 查 这 个 标识 的 另 一 个 可 能 的 原因 是 使 用 JNI ABORT 可 以 更 高 
效 。 例 如 ， 你 也 许 想 得 到 一 个 数组 ， 适 当地 修改 它 ， 传 入 部 分 到 其 他 函数 中 ， 然 后 丢掉 这 些 
修改 。 如 果 你 知道 JN| 是 为 你 做 了 一 份 新 的 拷贝 ， 就 没有 必要 再 创建 另 一 份 “ 可 编辑 的 
(editable) ”的 拷贝 了 。 如 果 JNI 传 给 你 的 是 原始 数组 ， 这 时 你 就 需要 创建 一 份 你 自己 的 拷贝 
了 。 


另 一 个 常见 的 错误 (在 示例 代码 中 出 现 过 ) 是 认为 当 isCopy 是 false 时 你 就 可 以 不 调用 
Release。 实 际 上 是 没有 这 种 情况 的 。 如 果 没 有 分 配备 份 空间 ， 那 么 初始 的 内 存 空 间 会 受到 牵 
制 ， 位 置 不 能 被 垃圾 回收 器 移动 。 


另外 注意 JNI_COMMIT 标 识 没有 释放 数组 ， 你 需要 使 用 一 个 不 同 的 标识 再 次 调用 
Release ° 
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当 你 想 做 的 只 是 拷 出 或 者 拷 进 数据 时 ， 可 以 选择 调用 像 GetArrayElements 和 GetStringChars 
这 类 非常 有 用 的 函数 。 想 想 下 面 : 


jbyte* data = env->GetByteArrayElements(array, NULL); 
if (data != NULL) { 


memcpy(buffer, data, len); 
env->ReleaseByteArrayElements(array, data, JNI_ABORT); 


这 里 获取 到 了 数组 ， 从 当中 拷贝 出 开头 的 len 个 字 节 元 素 ， 然 后 释放 这 个 数组 。 根 据 代 码 的 实 
现 ，Get 遂 数 将 会 这 制 或 者 拷贝 数组 的 内 容 。 上 面 的 代码 拷贝 了 数据 (为 了 可 能 的 第 二 次 ) > 
然后 调用 Release ; 这 当中 JNI ABORT 确 保 不 存在 第 三 份 拷贝 了 。 


另 一 种 更 简单 的 实现 方式 : 


env->GetByteArrayRegion(array, 0, len, buffer); 


这 种 方式 有 几 个 优点 : 


只 需要 调用 一 个 JNI 函 数 而 是 不 是 两 个 ， 减少 了 开销 。 
不 需要 指针 或 者 额外 的 拷贝 数据 。 


e. 减少 了 开发 人 员 犯 错 的 风险 -在 某 些 失败 之 后 忘记 调用 Release 不 存在 风险 。 


类 似 地 ， 你 能 使 用 SetArrayRegion 函 数 捞 贝 数据 到 数组 ， 使 用 GetStringRegion 或 者 
GetStringUTFRegion 从 String 中 拷贝 字符 。 
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nb 
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GH RAB MR T ELS eR] K SB 89 JNIE o RAS NR EC EL AERE (通过 函数 的 返回 值 ， 
ExceptionCheck > 34 zt ExceptionOccurred) ， 然 后 返回 ， 或 者 清除 异常 ， 处 理 掉 。 


当 异 常 发 生 时 你 被 允许 调用 的 JNI 函 数 有 : 


DeleteGlobalRef 
DeleteLocalRef 
DeleteWeakGlobalRef 
ExceptionCheck 
ExceptionClear 
ExceptionDescribe 
ExceptionOccurred 
MonitorExit 


e PopLocalFrame 

e PushLocalFrame 

e ReleaseArrayElements 

e ReleasePrimitiveArrayCritical 
e ReleaseStringChars 

e ReleaseStringCritical 

e ReleaseStringUTFChars 


许多 JNI 调 用 能 够 抛 出 异常 ， 但 通常 提供 一 种 简单 的 方式 来 检查 失败 。 例 如 ， 如 果 NewString 
返回 一 个 非 空 值 ， 你 不 需要 检查 异常 。 然 而 ， 如 果 你 调用 一 个 方法 〈 使 用 一 个 像 
CalllObjectMethod 的 函数 ) ， 你 必须 一 直 检 查 异 常 ， 因 为 当 一 个 异常 抛 出 时 它 的 返回 值 将 不 
会 是 有 效 的 。 


注意 中 断代 码 抛 出 的 异常 不 会 展开 本 地 调用 堆栈 信息 ，Android 也 还 不 支持 C++ 异常 。JNI 
Throw 和 ThrowNew 指 令 仅 仅 是 在 当前 线程 中 放 入 一 个 异常 指针 。 从 本 地 代码 返回 到 托管 代码 
时 ， 异 常 将 会 被 注意 到 ， 得 到 适当 的 处 理 。 


本 地 代码 能 够 通过 调用 ExceptionCheck 或 者 ExceptionOccurred 捕 获 到 异常 ， 然 后 使 用 
ExceptionClear 清 除 掉 。 通 常 ， 抛 弃 异 常 而 不 处 理会 导致 些 问题 。 


没有 内 建 的 函数 来 处 理 Throwable 对 象 自身 ， 因 此 如 果 你 想得到 红 常 字符 串 ， 你 需要 找 出 
Throwable Class， 然 后 查找 到 getMessage "()Ljava/lang/String;" 的 方法 ID， 调 用 它 ， 如 果 结 
果 非 空 ， 使 用 GetStringUTFChars， 得 到 的 结果 你 可 以 传 到 printf(3) 或 者 其 它 相 同 功 能 的 函数 
输出 。 


扩展 检查 


JNI 的 错误 检查 很 少 。 错 误 发 生 时 通常 会 导致 崩溃 。Android 也 提供 了 一 种 模式 ， 叫 做 
CheckJNI1， 这 当中 JavaVM 和 JNIEnv 辑 数 表 指针 被 换 成 了 函数 表 ， 它 在 调用 标准 实现 之 前 执 
行 了 一 系列 扩展 检查 的 。 


额外 的 检查 包括 : 


e 数组 : 试图 分 配 一 个 长 度 为 负 的 数组 。 

e. 坏 指针 : 传 入 一 个 不 完整 jarray/jclass/jobject/jstring 对 象 到 JNI 函 数 ， 或 者 调用 JNI 函 数 时 
使 用 空 指针 传 入 到 一 个 不 能 为 空 的 参数 中 去 。 

© 类 名 : 传 入 了 除 "java/lang/String" 之 外 的 类 名 到 JNI 函 数 。 

e 关键 调用 : 在 一 个 “关键 的 (critical)”"get 和 它 对 应 的 release 之 间 做 出 JNI 调 用 。 

直接 的 ByteBuffers : 传 入 不 正确 的 参数 到 NewDirectByteBuffer。 

e 异常 : 当 一 个 异常 发 生 时 调用 了 JNI 有 函数 。 

JNIEnvs : 在 错误 的 线程 中 使 用 一 个 JNIEnv。 

jfieldIDs : 使 用 一 个 空 jfieldID， 或 者 使 用 jfieldID 设 置 了 一 个 错误 类 型 的 值 到 字段 (比如 


说 ， 试 图 将 一 个 StringBuilder 赋 给 String 类 型 的 域 ) ， 或 者 使 用 一 个 静态 字段 下 的 jfieldID 
设置 到 一 个 实例 的 字段 (instance field) 反之 亦 然 ， 或 者 使 用 的 一 个 类 的 jfieldID 却 来 自 另 
一 个 类 的 实例 。 

e jmethodlDs : 当 调 用 Call*Method 肠 数 时 时 使 用 了 类 型 错误 的 jmethodID : 不 正确 的 返回 
值 ， 静 态 / 非 静 态 的 不 匹配 ，this 的 类 型 错误 (对 于 非 静 态 调用 ) 或 者 错误 的 类 (对 于 静态 
类 调用 ) 。 

e 引用 : 在 类 型 错误 的 引用 上 使 用 了 DeleteGlobalRefDeleteLocalRef 。 

e. 释放 模式 : 调用 release 使 用 一 个 不 正确 的 释放 模式 〈 其 它 非 > JNI ABORT > 
JNI_COMMIT 的 值 ) » 

e 类 型 安全 : 从 你 的 本 地 代码 中 返回 了 一 个 不 兼容 的 类 型 (比如 说 ， 从 一 个 声明 返回 String 
的 方法 却 返回 了 StringBuilder) ° 

e UTF-8 : 传 入 一 个 无 效 的 变形 UTF-8 字 节 序 列 到 JNI 调 用 。 


(方法 和 域 的 可 访问 性 仍然 没有 检查 : 访问 限制 对 于 本 地 代码 并 不 适用 。) 
有 几 种 方法 去 启用 CheckJNI1。 
如 果 你 正在 使 用 模拟 器 ，CheckJNI 默 认 是 打开 的 。 


如 果 你 有 一 台 root 过 的 设备 ， 你 可 以 使 用 下 面 的 命令 序列 来 重启 运行 时 (runtime) ， 启 用 
CheckJNI ° 


adb shell stop 
adb shell setprop dalvik.vm.checkjni true 
adb shell start 


随便 哪 一 种 ， 当 运行 时 (runtime) 启动 时 你 将 会 在 你 的 日 志 输出 中 见 到 如 下 的 字符 : 


D AndroidRuntime: CheckJNI is ON 


如 果 你 有 一 台 常 规 的 设备 ， 你 可 以 使 用 下 面 的 命令 : 


adb shell setprop debug.checkjni 1 


这 将 不 会 影响 已 经 在 运行 的 app， 但 是 从 那 以 后 启动 的 任何 app 都 将 打开 CheckJNI( 改 变 属性 
为 其 它 值 或 者 只 是 重启 都 将 会 再 次 关闭 CheckJNI)。 这 种 情况 下 ， 你 将 会 在 下 一 次 app 启 动 
时 ， 在 日 志 输 出 中 看 到 如 下 字符 : 


D Late-enabling CheckJNI 


本 地 库 


你 可 以 使 用 标准 的 System.loadLibrary 方 法 来 从 共享 库 中 加 载 本 地 代码 。 在 你 的 本 地 代码 中 较 
好 的 做 法 是 : 


。 在 一 个 静态 类 初始 化 时 调用 System.loadLibrary ( 见 之 前 的 一 个 例子 中 ， 当 中 就 使 用 了 
nativeClasslnit) 。 参 数 是 “未 加 修饰 (undecorated ) "的 库 名 称 ， 因 此 要 加 
A “libfubar.so” > f 4$ 324% A “fubar” » 

e. 提供 一 个 本 地 函数 : jint JNI OnLoad(JavaVM vm, void reserved) 

。 在 JNL_OnLoad 中 ， 注 册 所 有 你 的 本 地 方法 。 你 应 该 声明 方法 为 “静态 的 (static) "因此 名 
称 不 会 占据 设备 上 符号 表 的 空间 。 


JNIL_OnLoad 函 数 在 C++ 中 的 写法 如 下 : 


jint JNI OnLoad(JavaVM* vm, void* reserved) 
1 
JNIEnv* env; 
if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI VERSION 1 6) !- JNI OK) { 
return -1; 


} 


// 使 用 env->FindClass 得 到 jclass 





/ Hb Blan, ~ na otarkiat Lk wh st 
// 使 用 env->RegisterNatives 注 册 本 地 万 法 


return JNI VERSION 1 6; 


你 也 可 以 使 用 共享 库 的 全 路 径 来 调用 System.load。 对 于 Android app， 你 也 许 会 发 现 从 
context 对 象 中 得 到 应 用 私有 数据 存储 的 全 路 径 是 非常 有 用 的 。 


上 面 是 推荐 的 方式 ， 但 不 是 仅 有 的 实现 方式 。 显 式 注册 不 是 必须 的 ， 提 供 一 个 JNI_OnLoad 艺 
数 也 不 是 必须 的 。 你 可 以 使 用 基于 特殊 命名 的 “发现 (discovery) "模式 来 注册 本 地 方法 (更 多 
细节 见 : JNI spec) ， 虽 然 这 并 不 可 取 。 因 为 如 果 一 个 方法 的 签名 错误 ， 在 这 个 方法 实际 第 一 
次 被 调用 之 前 你 是 不 会 知道 的 。 


关于 JNIL_OnLoad 另 一 点 注意 的 是 : 任何 你 在 JNI_OnLoad 中 对 FindClass 的 调用 都 发 生 在 用 作 
加 载 共享 库 的 类 加 载 器 的 上 下 文 (context) 中 。 一 般 FindClass 使 用 与 “调用 栈 " 顶 部 方法 相关 

的 加 载 器 ， 如 果 当 中 没有 加 载 器 (因为 线程 刚刚 连接 ) 则 使 用 “系统 (system) "类 加 载 器 。 这 
就 使 得 JNL_OnLoad 成 为 一 个 查寻 及 缓存 类 引用 很 便利 的 地 方 。 


64 位 机 问题 


Android 当 前 设计 为 运行 在 32 位 的 平台 上 。 理 论 上 它 也 能 够 构建 为 64 位 的 系统 ， 但 那 不 是 现在 
的 目标 。 当 与 本 地 代码 交互 时 ， 在 大 多 数 情 况 下 这 不 是 你 需要 担心 的 ， 但 是 如 果 你 打算 存储 
指针 变量 到 对 象 的 整 型 字段 (integer field) 这 样 的 本 地 结构 中 ， 这 就 变 得 非常 重要 了 。 为 了 
支持 使 用 64 位 指针 的 架构 ， 你 需要 使 用 long 类 型 而 不 是 int 类 型 的 字段 来 存储 你 的 本 地 指针 。 


不 支持 的 特性 /向 后 兼容 性 


除了 下 面 的 例外 ， 支 持 所 有 的 JNI 1.6 特 性 


e DefineClass 没 有 实现 。Android 不 使 用 Java 字 节 码 或 者 class 文 件 ， 因 此 传 入 二 进 制 class 
数据 将 不 会 有 效 。 


对 Android 以 前 老 版 本 的 向 后 兼容 性 ， 你 需要 注意 : 


e. 本 地 函数 的 动态 查找 在 Android 2.0(Eclair) 之 前 ， 在 搜索 方法 名 称 时 ， 字 符 “$” 不 会 转换 为 
对 应 的 00024”。 要 使 它 正 常 工作 需要 使 用 显 式 注册 方式 或 者 将 本 地 方法 的 声明 移出 内 
部 类 。 

e 分 离线 程 在 Android 2.0(Eclaim) 之 前 ， 使 用 pthread key_create 析 构 有 函数 来 避免 "退出 前 线 

程 必须 分 离 " 检 查 是 不 可 行 的 (运行 时 (runtime) 也 使 用 了 一 个 pthread key 析 构 函 数 ， 因 此 

这 是 一 场 看 谁 先 被 调用 的 竞赛 ) 。 

全 局 弱 引 用 在 Android 2.0(Eclair) 之 前 ， 全 局 弱 引 用 没有 被 实现 。 如 果 试 图 使 用 它们 ， 老 

版 本 将 完全 不 兼容 。 你 可 以 使 用 Android 平 台 版 本 号 常量 来 测试 系统 的 支持 性 。 在 

Android 4.0 (Ice Cream Sandwich) 之 前 ， 全 局 弱 引 用 只 能 传 给 NewLocalRef, 

NewGlobalRef, 以 及 DeleteWeakGlobalRef (强烈 建议 开发 者 在 使 用 全 局 弱 引 用 之 前 都 为 

它们 创建 强 引用 hard reference， 所 以 这 不 应 该 在 所 有 限制 当中 ) 。 从 Android 4.0 (lce 

Cream Sandwich) 起 ， 全 局 弱 引 用 能 够 像 其 它 任何 JNI 引 用 一 样 使 用 了 。 

局 部 引用 在 Android 4.0 (Ice Cream Sandwich) 之 前 ， 局 部 引用 实际 上 是 直接 指针 。lce 

Cream Sandwich 为 了 更 好 地 支持 垃圾 回收 添加 了 间接 指针 ， 但 这 并 不 意味 着 很 多 JNI 

bug 在 老 版 本 上 不 存在 。 更 多 细节 见 JNI Local Reference Changes in ICS ° 

使 用 GetObjectRefType 获 得 引用 类 型 在 Android 4.0 (Ice Cream Sandwich) 之 前 ， 使 用 直 

接 指 针 ( 见 上 面 ) 的 后 果 就 是 正确 地 实现 GetObjectRefType 是 不 可 能 的 。 我 们 可 以 使 用 

依次 检测 全 局 弱 引 用 表 ， 参 数 ， 局 部 表 ， 全 局 表 的 方式 来 代替 。 第 一 次 匹配 到 你 的 直接 

指针 时 ， 就 表明 你 的 引用 类 型 是 当 eae 的 类 型 。 这 意味 着 ， 例 如 ， 如 果 你 在 一 个 

全 局 jclass 上 使 用 GetObjectRefType ， 个 全 局 jclass 碰 巧 与 作为 静态 本 地 方法 的 隐 式 

参数 传 入 的 jclass 一 样 的 ， 你 得 到 ee nn o 


FAQ: 为 什么 出 现 了 UnsatisfiedLinkError? 


当 使 用 本 地 代码 开发 时 经 常会 见 到 像 下 面 的 错误 : 


java.lang.UnsatisfiedLinkError: Library foo not found 


有 时 候 这 表示 和 它 提示 的 一 样 --- 未 找到 库 。 但 有 些 时 候 库 确实 存在 但 不 能 被 dlopen(3) 找 开 ， 
更 多 的 失败 信息 可 以 参见 异常 详细 说 明 。 


4% 38 F] “library not found" 异 常 的 常见 原因 可 能 有 这 些 : 


© 库 文件 不 存在 或 者 不 能 被 app 访 问 到 。 使 用 adb shell Is -| 检查 它 的 存在 性 和 权限 。 
e. 库 文件 不 是 用 NDK 构 建 的 。 这 就 导致 设备 上 并 不 存在 它 所 依赖 的 函数 或 者 库 。 


另 一 种 UnsatisfiedLinkError 错 误 像 下 面 这 样 : 


java.lang.UnsatisfiedLinkError: myfunc 
at Foo.myfunc(Native Method) 
at Foo.main(Foo.java:10) 


在 日 志 中 ， 你 会 发 现 : 


W/dalvikvm( 880): No implementation found for native LFoo;.myfunc ()V 


这 意味 着 运行 时 尝试 匹配 一 个 方法 但 是 没有 成 功 ， 这 种 情况 常见 的 原因 有 : 


e 库 文件 没有 得 到 加 载 。 检 查 日 志 输 出 中 关于 库 文件 加 载 的 信息 。 
e 由 于 名 称 或 者 签名 错误 ， 方 法 不 能 匹配 成 功 。 这 通常 是 由 于 : 
o 对 于 方法 的 懒 查寻 ， 使 用 extern "C" 和 对 应 的 可 见 性 (JNIEXPORT) 来 声明 C++ 函 
数 没 有 成 功 。 注 意 lce Cream Sandwich 之 前 的 版 本 ，JNIEXPORT 宏 是 不 正确 的 ， 
此 对 新 版 本 的 GCC 使 用 昌 的 jni.h 头 文件 将 不 会 有 效 。 你 可 以 使 用 arm-eabi-nm 查 看 它 
们 出 现在 库 文件 里 的 符号 。 如 果 它 们 看 上 去 比较 凌乱 (1% 
_Z15Java_Foo_myfuncP7_JNIEnvP7_jclass 这 样 而 不 是 Java Foo myfunc) ， 或 者 
符号 类 型 是 小 写 的 中 而 不 是 一 个 大 写 的 "T”, 这 时 你 就 需要 调整 声明 了 。 
o 对 于 显 式 注册 ， 在 进行 方法 签名 时 可 能 犯 了 些小 错误 。 确 保 你 传 入 到 注册 函数 的 签 
名 能 够 完全 匹配 上 日 志文 件 里 提示 的 。 记 住 "B" 是 byte ，"“Z" 是 boolean。 在 签名 中 类 
名 组 件 是 以 “L" 开 头 的 ， 以 “,” 结 束 的 ， 使 用 “来 分 隔 包 名 /类 名 ， 使 用 "“$”" 符 来 分 隔 内 部 
类 名 称 ( 比如 说 ，Ljaval/util/Map$Entry;) ° 


使 用 javah 来 自动 生成 JNI 头 文件 也 许 能 帮助 你 避免 这 些 问题 。 


FAQ: 为 什么 FindClass 不 能 找到 我 的 类 ? 


确保 类 名 字符 串 有 正确 的 格式 。JNI 类 名 称 以 包 名 开始 ， 然 后 使 用 左 斜 杠 来 分 隔 ， 比 如 
java/lang/String。 如 果 你 正在 查找 一 个 数组 类 ， 你 需要 以 对 应 数目 的 综 括 号 开头 ， 使 
用 “L” 和 “;” 将 类 名 两 头 包 起 来 ， 所 以 一 个 一 维 字 符 串 数组 应 该 写成 [Ljava/lang/String;。 


如 果 类 名 称 看 上 去 正确 ， 你 可 能 运行 时 遇 到 了 类 加 载 器 的 问题 。FindClass 想 在 与 你 代码 相关 
的 类 加 载 器 中 开始 查找 指定 的 类 。 检 查 调 用 堆栈 ， 可 能 看 起 像 : 


Foo.myfunc(Native Method) 
Foo.main(Foo.java:10) 
dalvik.system.NativeStart.main(Native Method) 


最 顶层 的 方法 是 Foo.myfunc。FindClass 找 到 与 类 Foo 相 关 的 ClassLoader 对 象 然后 使 用 它 。 


就 会 遇 到 麻烦 (也 许 是 调用 了 


这 通常 正 是 你 所 想 的 。 如 果 你 创建 了 自己 的 线程 那么 就 
了 连接 ) 。 现 在 跟踪 堆栈 可 能 像 下 面 这 


pthread_create 然 后 使 用 AttachCurrentThread 进 行 
样 : 


dalvik.system.NativeStart.run(Native Method) 


最 顶层 的 方法 是 NativeStart.run， 它 不 是 你 应 用 内 的 方法 。 如 果 你 从 这 个 线程 中 调用 
FindClass，JavaVM 将 会 启动 “系统 (system) “的 而 不 是 与 你 应 用 相关 的 加 载 器 ， 因 此 试图 查 
找 应 用 内 定义 的 类 都 将 会 失败 。 


下 面 有 几 种 方法 可 以 解决 这 个 问题 : 


e 在 JNI _ OnLoad 中 使 用 FindClass 查 寻 一 次 ， 然 后 为 后 面 的 使 用 缓存 这 些 类 引用 。 任 何在 
JNI OnLoad 妆 中 执行 的 FindClass 调 用 都 使 用 与 执行 System.loadLibrary 的 函数 相关 的 类 
加 载 器 (这 个 特例 ， 让 库 的 初始 化 更 加 的 方便 了 ) 。 如 果 你 的 app 代 码 正 在 加 载 库 文件 ， 
FindClass 将 会 使 用 正确 的 类 加 载 器 。 

e 传 入 类 实例 到 一 个 需要 它 的 函数 ， 你 的 本 地 方法 声明 必须 带 有 一 个 Class 参 数 ， 然 后 传 入 
Foo.class ° 

e 在 合适 的 地 方 缓存 一 个 ClassLoader 对 象 的 引用 ， 然 后 直接 发 起 loadClass 调 用 。 这 需要 
额外 些 工 作 。 


FAQ: 使 用 本 地 代码 怎样 共享 原始 数据 ? 


也 许 你 会 遇 到 这 样 一 种 情况 ， 想 从 你 的 托管 代码 或 者 本 地 代码 访问 一 大 块 原始 数据 的 缓冲 
区 。 常 见 例子 包括 对 bitmap 或 者 声音 文件 的 处 理 。 这 里 有 两 种 基本 实现 方式 。 


你 可 以 将 数据 存储 到 byte[]。 这 允许 你 从 托管 代码 中 快速 地 访问 。 然 而 ， 在 本 地 代码 端 不 能 保 
证 你 不 去 拷贝 一 份 就 直接 能 够 访问 数据 。 在 某 些 实现 中 ，GetByteArrayElements 和 
GetPrimitiveArrayCritical 将 会 返回 指向 在 维护 堆 中 的 原始 数据 的 丨 实 指针 ， 但 是 在 另外 一 些 实 
现 中 将 在 本 地 堆 空 间 分 配 一 块 缓冲 区 然后 拷贝 数据 过 去 。 


还 有 一 种 选择 是 将 数据 存储 在 一 块 直接 字 节 缓冲 区 (direct byte buffer) ， 可 以 使 用 
java.nio.ByteBuffer.allocateDirect x #4 NewDirectByteBuffer JNI 函 数 创 建 buffer。 不 像 常规 的 
byte 缓 冲 区 ， 它 的 存储 空间 将 不 会 分 配 在 程序 维护 的 堆 空 间 上 ， 总 是 可 以 从 本 地 代码 直接 访问 

(使 用 GetDirectBufferAddress 得 到 地 址 ) 。 依 赖 于 直接 字 节 缓冲 区 访问 的 实现 方式 ， 从 托管 
代码 访问 原始 数据 将 会 非常 慢 。 


选择 使 用 哪 种 方式 取决 于 两 个 方面 : 
1. 大 部 分 的 数据 访问 是 在 Java 代 码 还 是 C/C++ 代码 中 发 生 ? 


2. 如 果 数 据 最 终 被 传 到 系统 API， 那 它 必 须 是 怎样 的 形式 〈 例 如， 如 果 数 据 最 终 被 传 到 一 个 使 
用 byte[] 作 为 参数 的 函数 ， 在 直接 的 ByteBuffer 中 处 理 或 许 是 不 明智 的 ) ? 


如 果 通过 上 面 两 种 情况 仍然 不 能 明确 区 分 的 ， 就 使 用 直接 字 节 缓冲 区 (direct byte buffer) 形 
式 。 它 们 的 支持 是 直接 构建 到 JNI 中 的 ， 在 未 来 的 版 本 中 性 能 可 能 会 得 到 提升 。 


SMP(Symmetric Multi-Processor) Primer 
for Android 


^h 5 :Kesenhoo - /$. X :http://developer.android.com/training/articles/smp.html 


从 Android 3.0 开 始 ， 系 统 针 对 多 核 CPU 架 构 的 机 器 做 了 优化 支持 。 这 份 文档 介绍 了 针对 多 核 
系统 应 该 如 何 编写 C，C++ 以 及 Java 程 序 。 这 里 只 是 作为 Android 应 用 开发 者 的 入 门 教 程 ， 并 
不 会 深入 讨论 这 个 话题 ， 并 且 我 们 会 把 讨论 范围 集中 在 ARM 架 构 的 CPU 上 。 


如 果 你 并 没有 时 间 学 习 整 篇 文章 ， 你 可 以 跳 过 前 面 的 理论 部 分 ， 直 接 查 看 实践 部 分 。 但 是 我 
们 并 不 建议 这 样 做 。 


AA 

0) 简 要 介绍 

SMP 的 全 称 是 ‘Symmetric Multi-Processor" ^ 它 表 示 的 是 一 种 双核 或 者 多 核 CPU 的 设计 架 
构 。 在 几 年 前 ， 所 有 的 Android 设 备 都 还 是 单 核 的 。 


大 多 数 的 Android 设 备 已 经 有 了 多 个 CPU， 但 是 通常 来 说 ， 其 中 一 个 CPU 负责 执行 程序 ， 其 他 
的 CPU 则 处 理 设 备 硬件 的 相关 事务 (例如 ， 音 频 ) 。 这 些 CPU 可 能 有 着 不 同 的 架构 ， 和 运行 在 
上 面 的 程序 无 法 在 内 存 中 彼此 进行 沟通 交互 。 


目前 大 多 数 售卖 的 Android 设 备 都 是 SMP 架 构 的 ， 这 使 得 软件 开发 者 处 理 问题 更 加 复杂 。 对 于 
多 线程 的 程序 ， 如 果 多 个 线程 执行 在 不 同 的 内 核 上 ， 这 会 使 得 程序 更 加 容易 发 生 race 
conditions 。 更 糟糕 的 是 ， 基 于 ARM 架 构 的 SMP 比 起 x86 架 构 来 说 ， 更 加 复杂 ， 更 难 进行 处 
理 。 那 些 在 x86 上 测试 通过 的 程序 可 能 会 在 ARM 上 崩溃 。 


下 面 我 们 会 介绍 为 何 会 这 样 以 及 如 何 做 才能 够 使 得 你 的 代码 行为 正常 。 
1) 理 论 篇 


这 里 会 快速 并 且 简 要 的 介绍 这 个 复杂 的 主题 。 其 中 一 些 部 分 并 不 完整 ， 但 是 并 没有 出 现 错误 
或 者 误导 。 


查看 文章 末尾 的 进一步 阅读 可 以 了 解 这 个 主题 的 更 多 知识 。 


1.1) 内 存 一 致 性 模型 (Memory consistency models) 


内 存 一 致 性 模型 (Memory consistency models) 通 常 也 被 叫做 “memory models" > 453€ f ARE 
架构 如 何 确保 内 郁 访 问 的 一 臻 性。 例如， 如 果 你 对 地 址 A 进行 了 一 个 赋值 ， 然 后 对 地 址 B 也 进 
行 了 赋值 ， 那 么 内 存 一 致 性 模型 就 需要 确保 每 一 个 CPU 都 需要 知道 刚才 的 操作 赋值 与 操作 顺 
序 。 


这 个 模型 通常 被 程序 员 称 为 : 顺序 一 致 性 (sequential consistency), 请 从 文章 末尾 的 进一步 
阅读 查看 Adve & Gharachorloo 这 篇 文章 。 


e 所 有 的 内 存 操作 每 次 只 能 执行 一 个 。 
e 所 有 的 操作 ， 在 单 核 CPU 上 ， 都 是 顺序 执行 的 。 


如 果 你 关注 一 段 代码 在 内 存 中 的 读 写 操作 ， 在 sequentially-consistent 的 CPU 架构 上 ， 是 按照 
期 待 的 顺序 执行 的 。lts possible that the CPU is actually reordering instructions and 
delaying reads and writes, but there is no way for code running on the device to tell that the 
CPU is doing anything other than execute instructions in a straightforward manner. (We're 
ignoring memory-mapped device driver I/O for the moment.) 


To illustrate these points it's useful to consider small snippets of code, commonly referred to 
as litmus tests. These are assumed to execute in program order, that is, the order in which 
the instructions appear here is the order in which the CPU will execute them. We don't want 
to consider instruction reordering performed by compilers just yet. 


Here's a simple example, with code running on two threads: 


Thread 1 Thread 2 A = 3 B = 5 reg0 = B reg1 =A 


Thread 1 Thread 2 
A=3B=5 rego = B reg1 =A 


In this and all future litmus examples, memory locations are represented by capital letters (A, 
B, C) and CPU registers start with “reg”. All memory is initially zero. Instructions are 
executed from top to bottom. Here, thread 1 stores the value 3 at location A, and then the 
value 5 at location B. Thread 2 loads the value from location B into regO, and then loads the 
value from location A into reg1. (Note that we're writing in one order and reading in another.) 


Thread 1 and thread 2 are assumed to execute on different CPU cores. You should always 
make this assumption when thinking about multi-threaded code. 


Sequential consistency guarantees that, after both threads have finished executing, the 
registers will be in one of the following states: 


Registers States 


reg0=5, reg1=3 possible (thread 1 ran first) 
reg0=0, regi=0 possible (thread 2 ran first) 
reg0=0, reg1=3 possible (concurrent execution) 
reg0=5, regi=0 never 


To get into a situation where we see B=5 before we see the store to A, either the reads or 
the writes would have to happen out of order. On a sequentially-consistent machine, that 
can't happen. 


Most uni-processors, including x86 and ARM, are sequentially consistent. Most SMP 
systems, including x86 and ARM, are not. 


1.1.1)Processor consistency 
1.1.2)CPU cache behavior 
1.1.3)Observability 
1.1.4)ARM's weak ordering 
1.2)Data memory barriers 
1.2.1)Store/store and load/load 
1.2.2)Load/store and store/load 
1.2.3)Barrier instructions 
1.2.4)Address dependencies and causal consistency 
1.2.5)Memory barrier summary 
1.3)Atomic operations 


1.3.1)Atomic essentials 


1.3.2)Atomic + barrier pairing 


1.3.3)Acquire and release 


2) 实 践 篇 


调试 内 存 一 致 性 (memory consistency) 的 问题 非常 困难 。 如 果 内 存 栅栏 Imemory barrier) 3- 5 
一 些 代码 读 取 到 陈旧 的 数据 ， 你 将 无 法 通过 调试 器 检查 内 存 dumps 文 件 来 找 出 原因 。By the 
time you can issue a debugger query, the CPU cores will have all observed the full set of 
accesses, and the contents of memory and the CPU registers will appear to be in an 
“impossible” state. 


2.1)What not to do in C 
2.1.1)C/C++ and "volatile" 
2.1.2)Examples 


2.2) 在 Java 中 不 应 该 做 的 事 


我 们 没有 讨论 过 Java 语 言 的 一 些 相关 特 性 ， 因 此 我 们 首先 来 简要 的 看 下 那些 特性 。 


2.2.1)Java "synchronized" 5 "volatile" 关键 字 


“synchronized” 关 键 字 提 供 了 Java 一 种 内 置 的 锁 机 制 。 每 一 个 对 象 都 有 一 个 相对 应 
的 “monitor”， 这 个 监听 器 可 以 提供 互 不 的 访问 。 


“synchronized” 代 码 段 的 实现 机 制 与 自 旋 锁 (spin lock) 有 着 相同 的 基础 结构 : 他 们 都 是 从 获取 到 
CAS 开 始 ， 以 释放 CAS 结 束 。 这 意味 着 编译 器 (compilers) 与 代码 优化 器 (code optimizers) 可 以 
轻松 的 迁移 代码 到 “synchronized” 代 码 段 中 。 一 个 实践 结果 是 : 你 不 能 判定 Synchronized 代 码 
段 是 执行 在 这 段 代 码 下 面 一 部 分 的 前 面 ， 还 是 这 段 代 码 上 面 一 部 分 的 后 面 。 更 进一步 ， 如 果 
一 个 方法 有 两 个 synchronized 代 码 段 并 且 锁 住 的 是 同一 个 对 象 ， 那 么 在 这 两 个 操作 的 中 间 代 码 
都 无 法 被 其 他 的 线程 所 检测 到 ， 编 译 器 可 能 会 执行 “ 锁 粗 化 lock coarsening”" 并 且 把 这 两 者 绑 定 
到 同一 个 代码 块 上 。 


另外 一 个 相关 的 关键 字 是 “Volatile”。 在 Java 1.4 以 及 之 前 的 文档 中 是 这 样 定义 的 : volatile # 
明和 对 应 的 C 语 言 中 的 一 样 可 不 靠 。 从 Java 1.5 开 始 ， 提 供 了 更 有 力 的 保障 ， 甚 至 和 
synchronization 一 样 具备 强 同步 的 机 制 。 


volatile 的 访问 效果 可 以 用 下 面 这 个 例子 来 说 明 。 如 果 线 程 1 给 volatile 字 段 做 了 赋值 操作 ， 线 程 
2 紧 接 着 读 取 那 个 字段 的 值 ， 那 么 线程 2 是 被 确保 能 够 查看 到 之 前 线程 1 的 任何 写 操作 。 更 通常 
的 情况 是 ， 任 何 线程 对 那个 字段 的 写 操作 对 于 线程 2 来 说 都 是 可 见 的 。 实 际 上 ， 写 volatile 就 像 
是 释放 件 监 听 器 ， 读 volatile 就 像 是 获取 监听 器 。 


非 volatile 的 访问 有 可 能 因为 照顾 volatile 的 访问 而 需要 做 顺序 的 调整 。 例 如 编译 器 可 能 会 往 上 
移动 一 个 非 volatile 加 载 操 作 ， 但 是 不 会 往 下 移动 。Volatile 之 间 的 访问 不 会 因为 彼此 而 做 出 顺 
序 的 调整 。 虚 拟 机 会 注意 处 理 如 何 的 内 存 栅 栏 (memory barriers) ° 


当 加 载 与 保存 大 多 数 的 基础 数据 类 型 ， 他 们 都 是 原子 的 atomic, 对 于 long 以 及 double 类 型 的 数 
据 则 不 具备 原子 型 ， 除 非 他 们 被 声明 为 volatile。 即 使 是 在 单 核 处 理 器 上 ， 并 发 多 线程 更 新 非 
volatile 字 段 值 也 还 是 不 确定 的 。 


2.2.2)Examples 


下 面 是 一 个 错误 实现 的 单 步 计 数 器 (monotonic counter) 的 示例 : (Java theory and practice: 
Managing volatility). 


class Counter { 
private int mValue; 


public int get() { 
return mValue; 


} 
public void incr() { 
mValue-c-; 


} 


假设 get() 与 incr() 方 法 是 被 多 线程 调用 的 。 然 后 我 们 想 确保 当 get() 方 法 被 调用 时 ， 每 一 个 线程 
都 能 够 看 到 当前 的 数量 。 最 引 人 注 目的 问题 是 mValue++ 实 际 上 包含 了 下 面 三 个 操作 。 


1. reg = mValue 
2. reg - reg * 1 
3. mValue = reg 


如 果 两 个 线程 同时 在 执行 incr() 方法 ， 其 中 的 一 个 更 新 操作 会 丢失 。 为 了 确保 正确 的 执 

行 ++ 的 操作 ， 我 们 需要 把 inro 方法 声明 为 “synchronized”。 这 样 修改 之 后 ， 这 段 代 码 才 
能 够 在 单 核 多 线程 的 环境 中 正确 的 执行 。 

然而 ， 在 SMP 的 系统 下 还 是 会 执行 失败 。 不 同 的 线程 通过 get() 方法 获取 到 得 值 可 能 是 不 一 


样 的 。 因 为 我 们 是 使 用 通常 的 加 载 方 式 来 读 取 这 个 值 的 。 我 们 可 以 通过 声明 get() 方法 为 
synchronized 的 方式 来 修正 这 个 错误 。 通 过 这 些 修改 ， 这 样 的 代码 才 是 正确 的 了 。 


不 幸 的 是 ， 我 们 有 介绍 过 有 可 能 发 生 的 锁 竞争 (lock contention)， 这 有 可 能 会 伤害 到 程序 的 性 

能 。 除 了 声明 get() 方法 为 synchronized 之 外 ， 我 们 可 以 声明 mvalue X “volatile”. (请 注 

意 incr() 必须 使 用 synchronize) 现在 我 们 知道 volatile 的 mValue 的 写 操 作对 于 后 续 的 读 操作 

pop 。 incr() 将 会 稍稍 有 点 变 慢 ， 但 是 get() 方法 将 会 变 得 更 加 快速 。 因 此 读 操 作 多 
操作 时 ， 这 会 是 一 个 比较 好 的 方案 。( 请 参考 Atomiclnteger ) 


下 面 是 另外 一 个 示例 ， 和 之 前 的 C 示 例 有 点 类 似 : 


class MyGoodies { 
public int x, y; 
} 
class MyClass { 
static MyGoodies sGoodies; 
void initGoodies() { // runs in thread 1 
MyGoodies goods - new MyGoodies(); 
goods.x = 5; 
goods.y - 10; 
sGoodies - goods; 
} 
void useGoodies() { // runs in thread 2 
zm 人 != null) { 
int i = sGoodies.x; // could be 5 or O 
} 
} 
} 


这 段 代 码 同样 存在 着 问题 ， sGoodies = goods 的 赋值 操作 有 可 能 在 goods 成 员 变 量 赋值 之 前 
被 察觉 到 。 如 果 你 使 用 volatile 声明 sGoodies 变量 ， 你 可 以 认为 load 操 作 
为 atomic acquire load() ， 并 且 把 store 操 作 认 为 是 atomic release store() ? 


(请 注意 仅仅 是 sGoodies 的 引用 本 身 为 volatile ， 访 问 它 的 内 部 字段 并 不 是 这 样 的 。 赋 值 语 
4] z = sGoodies.x 会 执行 一 个 volatile load MyClass.sGoodies 的 操作 ， 其 后 会 伴随 一 个 non- 
volatile 的 load 操 作 : : sGoodies.x 。 如 果 你 设置 了 一 个 本 地 引用 MyGoodies localGoods = 


sGoodies，z = localGoods.x ， 这 将 不 会 执行 任何 volatile loads.) 


另外 一 个 在 Java 程 序 中 更 加 常用 的 范式 就 是 臭名 昭著 的 “double-checked locking": 


class MyClass { 
private Helper helper = null; 


public Helper getHelper() { 
if (helper == null) { 
synchronized (this) { 
if (helper == null) { 
helper = new Helper(); 
} 
} 
} 


return helper; 


上 面 的 写法 是 为 了 获得 一 个 MyClass 的 单 例 。 我 们 只 需要 创建 一 次 这 个 实例 ， 通 

过 getHelper() 这 个 方法 。 为 了 避免 两 个 线程 会 同时 创建 这 个 实例 。 我 们 需要 对 创建 的 操作 加 
synchronize 机 制 。 然 而 ， 我 们 不 想 要 为 了 每 次 执行 这 段 代 码 的 时 候 都 为 "synchronized" 付 出 额 
外 的 代价 ， 因 此 我 们 仅仅 在 helper 对 象 为 空 的 时 候 加 锁 。 


在 单 核 系统 上 ， 这 是 不 能 正常 工作 的 。JIT 编 译 器 会 破坏 这 件 事情 。 请 查看 4)Appendix 
的 “Double Checked Locking is Broken’ Declaration” 获 取 更 多 的 信息 , 或 者 是 Josh Bloch's 
Effective Java 书 中 的 ltem 71 (“Use lazy initialization judiciously”) » 


在 SMP 系 统 上 执行 这 段 代码 ， 引 入 了 一 个 额外 的 方式 会 导致 失败 。 把 上 面 那 段 代 码 换 成 C 的 语 
言 实 现 如 下 : 


if (helper == null) { 
// acquire monitor using spinlock 
while (atomic_acquire_cas(&this.lock, 9, 1) != success) 
if (helper == null) { 
newHelper = malloc(sizeof(Helper)); 
newHelper->x = 5; 
newHelper->y = 10; 
helper = newHelper; 


} 


atomic_release_store(&this.lock, 0); 


此 时 问题 就 更 加 明显 了 : helper 的 store 操 作 发 生 在 memory barrier 之 前 ， 这 意味 着 其 他 的 线 
程 能 够 在 store x/y 之 前 观察 到 非 空 的 值 。 


你 应 该 尝试 确保 store helper 执 行 在 atomic release store() 方法 之 后 。 通 过 重新 排序 代码 进 
行 加 锁 ， 但 是 这 是 无 效 的 ， 因 为 往 上 移动 的 代码 ， 编 译 器 可 以 把 它 移 动 回 原来 的 位 置 : 
在 atomic release store() 前 面 。 (这 里 没有 读 ， HE > ， 下 次 再 回 读 ) 


有 2 个 方法 可 以 解决 这 个 问题 : 


e 删除 外 层 的 检查 。 这 确保 了 我 们 不 会 在 synchronized 代 码 段 之 外 做 任何 的 检查 。 
声明 helper 为 volatile。 仅 仅 这 样 一 个 小 小 的 修改 ， 在 前 面 示例 中 的 代码 就 能 够 在 Java 1.5 
Becr 工作 。 


下 面 的 示例 演示 了 使 用 volatile 的 2 各 重要 问题 : 


class MyClass ( 
int data1, data2; 
volatile int voli, vol2; 





void setValues() { // runs in thread 1 
data1 = 1; 
VOIR — 2 
data2 = 3; 
} 
void useValuesi() { // runs in thread 2 
if (voli == 2) { 
int 11 = datai; // okay 
int 12 - data2; // wrong 
} 
} 
void useValues2() { // runs in thread 2 
int dummy = vol2; 
int 11 = data1; // wrong 
int 12 = data2; // wrong 
} 


请 注意 usevaluesi() ， 如 果 thread 2 还 没有 察觉 到 volt 的 更 新 操作 ， 那 么 pH 

道 datal 或 者 data2 被 设置 的 操作 。 一 旦 它 观察 到 了 voii 的 更 新 操作 ， 和 那么 能 够 知道 
data1 的 更 新 操作 。 然 而 ， 对 于 data2 则 无 法 做 任何 猜测 ， B E store 之 
后 发 生 的 。 


ENS 使 用 了 第 2 个 volatile 字 段 : vol2， 这 会 强制 VM 生 成 一 个 memory barrier » 3x 34 
常 不 会 发 生 。 为 了 建立 一 个 恰当 的 “happens-before” 关 系 ，2 个 线程 都 需要 使 用 同一 个 volatile 
字段 。 在 thread 1 中 你 需要 知道 vol2 是 在 data1/data2 之 后 被 设置 的 。(The fact that this 
doesn't work is probably obvious from looking at the code; the caution here is against trying 
to cleverly "cause" a memory barrier instead of creating an ordered series of accesses.) 


2.3)What to do 


2.3.1)General advice 


在 C/C++ 中 ， 使 用 pthread 3&1EF > | demutexes 5 semaphores ° 1&1] 21% Jf] &3é 4 memory 
barriers， 在 所 有 的 Android 平 台 上 提供 正确 有 效 的 行为 。 请 确保 正确 这 些 技术 ， 例 如 在 没有 获 
得 对 应 的 mutex 的 情况 下 赋值 操作 需要 很 说 惯 。 


避免 直接 使 用 atomic 方 法 。 如 果 locking 与 Unlocking 之 间 没 有 竞争 ，locking 与 unlocking 一 个 
pthread mutex 分 别 需 要 一 个 单独 的 atomic 操 作 。 如 果 你 需要 一 个 lock-free 的 设计 ， 你 必须 在 
开始 写 代码 之 前 了 解 整 篇 文档 的 要 点 。 (或 者 是 寻找 一 个 已 经 为 SMP ARM 设 计 好 的 库 文 

件 ) 。 


Be extremely circumspect with "volatile" in C/C++. It often indicates a concurrency problem 
waiting to happen. 


In Java, the best answer is usually to use an appropriate utility class from the 
java.util.concurrent package. The code is well written and well tested on SMP. 


Perhaps the safest thing you can do is make your class immutable. Objects from classes like 
String and Integer hold data that cannot be changed once the class is created, avoiding all 
synchronization issues. The book Effective Java, 2nd Ed. has specific instructions in "Item 
15: Minimize Mutability Note in particular the importance of declaring fields "final" (Bloch). 


If neither of these options is viable, the Java "synchronized" statement should be used to 
guard any field that can be accessed by more than one thread. If mutexes won't work for 
your situation, you should declare shared fields "volatile", but you must take great care to 
understand the interactions between threads. The volatile declaration won't save you from 
common concurrent programming mistakes, but it will help you avoid the mysterious failures 
associated with optimizing compilers and SMP mishaps. 


The Java Memory Model guarantees that assignments to final fields are visible to all threads 
once the constructor has finished — this is what ensures proper synchronization of fields in 
immutable classes. This guarantee does not hold if a partially-constructed object is allowed 
to become visible to other threads. It is necessary to follow safe construction practices.(Safe 
Construction Techniques in Java). 


2.3.2)Synchronization primitive guarantees 


The pthread library and VM make a couple of useful guarantees: all accesses previously 
performed by a thread that creates a new thread are observable by that new thread as soon 
as it starts, and all accesses performed by a thread that is exiting are observable when a 
join() on that thread returns. This means you don't need any additional synchronization when 
preparing data for a new thread or examining the results of a joined thread. 


Whether or not these guarantees apply to interactions with pooled threads depends on the 
thread pool implementation. 


In C/C++, the pthread library guarantees that any accesses made by a thread before it 
unlocks a mutex will be observable by another thread after it locks that same mutex. It also 
guarantees that any accesses made before calling signal() or broadcast() on a condition 
variable will be observable by the woken thread. 


Java language threads and monitors make similar guarantees for the comparable 
operations. 


2.3.3)Upcoming changes to C/C++ 


The C and C++ language standards are evolving to include a sophisticated collection of 
atomic operations. A full matrix of calls for common data types is defined, with selectable 
memory barrier semantics (choose from relaxed, consume, acquire, release, acq rel, 
seq cst). 


See the Further Reading section for pointers to the specifications. 


3)Closing Notes 


While this document does more than merely scratch the surface, it doesn't manage more 
than a shallow gouge. This is a very broad and deep topic. Some areas for further 
exploration: 


e Learn the definitions of happens-before, synchronizes-with, and other essential 
concepts from the Java Memory Model. (It's hard to understand what "volatile" really 
means without getting into this.) 

e Explore what compilers are and aren't allowed to do when reordering code. (The JSR- 
133 spec has some great examples of legal transformations that lead to unexpected 
results.) 

e Find out how to write immutable classes in Java and C++. (There's more to it than just 
"don't change anything after construction".) 

e Internalize the recommendations in the Concurrency section of Effective Java, 2nd 
Edition. (For example, you should avoid calling methods that are meant to be 
overridden while inside a synchronized block.) 

e Understand what sorts of barriers you can use on x86 and ARM. (And other CPUs for 
that matter, for example Itanium's acquire/release instruction modifiers.) 

e Read through the java.util.concurrent and java.util.concurrent.atomic APIs to see 
what's available. 

e Consider using concurrency annotations like @ThreadSafe and @GuardedBy (from 
net.jcip.annotations). 


The Further Reading section in the appendix has links to documents and web sites that will 
better illuminate these topics. 


4)Appendix 
4.1)SMP failure example 
4.2))mplementing synchronization stores 


4.3)Further reading 


Android 安 全 与 隐私 


保护 安全 与 隐私 的 最 佳 策略 


编写 :craftsmanBai - http://z1ng.net - 原文 :http://developer.android.com/training/best- 
security.html 


下 面 的 课程 教 你 如 何 确保 应 用 程序 数据 的 安全 。 


KERA 


怎样 执 在 执行 多 个 任务 的 同时 确保 应 用 程序 数据 和 用 户 数据 的 安全 。 


HTTPS 和 SSL 的 安全 


如 何 确保 应 用 程序 在 进行 网 络 传输 时 是 安全 的 。 


更 新 你 的 Security Provider 对 抗 SSL 漏 洞 攻击 


如 何 使 用 和 更 新 Google Play services security provider X xi 4tSSL 788] xX ds » 


企业 级 开发 


如 何 为 企业 级 应 用 程序 实施 设备 管理 策略 。 
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^h '5 :craftsmanBai - http://z1ng.net - 原 
x-:http;//developer.android.com/training/articles/security-tips.html 


Android 内 建 的 安全 机 制 可 以 显著 地 减少 了 应 用 程序 的 安全 问题 。 你 可 以 在 默认 的 系统 设置 和 
文件 权限 设置 的 环境 下 建立 应 用 ， 避 免 针 对 一 堆 头 次 的 安全 问题 寻找 解决 方案 。 


一 些 帮 助 建立 应 用 的 核心 安全 特性 如 下 : 


e Android 应 用 程序 沙 盒 ， 将 应 用 数据 和 代码 的 执行 与 其 他 程序 隔离 。 

e 具有 和 鲁 棒 性 的 常见 安全 功能 的 应 用 框架 ， 例 如 加 密 ， 权 限 控制 ， 安 全 IPC 

e 使 用 ASLR，NX，ProPolice > safe iop，OpenBSD dlmalloc * OpenBSD calloc > Linux 
mmap_min_addr 等 技术 ， 减 少 了 常见 内 存 管理 错误 。 

© 加 密 文件 系统 可 以 保护 丢失 或 被 盗 走 的 设备 数据 。 

e 用 户 权 限 控 制 限制 访问 系统 关键 信息 和 用 户 数据 。 

e 应 用 程序 权限 以 单个 应 用 为 基础 控制 其 数据 。 


尽管 如 此 ， 熟 悉 Android 安 全 特性 仍然 很 重要 。 遵 守 这 些 习惯 并 将 其 作为 优秀 的 代码 风格 ， 能 
够 减少 无 意 间 给 用 户 带 来 的 安全 问题 。 


数据 存储 


对 于 一 个 Android 的 应 用 程序 来 说 ， 最 为 常见 的 安全 问题 是 存放 在 设备 上 的 数据 能 否 被 其 他 应 
用 获取 。 在 设备 上 存放 数据 基本 方式 有 三 种 : 


使 用 内 部 存储 


默认 情况 下 ， 你 在 内 部 存储 中 创建 的 文件 只 有 你 的 应 用 可 以 访问 。Android 实 现 了 这 种 机 制 ， 
并 且 对 于 大 多 数 应 用 程序 都 是 有 效 的。 你 应 该 避免 在 IPC 文 件 中 使 

用 MODE_WORLD _WRITEABLE 或 者 MODE_WORLD_READABLE 模 式 ， 因 为 它们 不 为 特殊 
程序 提供 限制 数据 访问 的 功能 ， 它 们 也 不 对 数据 格式 进行 任何 控制 。 如 果 你 想 与 其 他 应 用 的 
进程 共享 数据 ， 可 以 使 用 Content Provider， 它 可 以 给 其 他 应 用 提供 了 可 读 写 权限 以 及 逐 项 动 
态 获 取 权 限 。 


如 果 想 对 敏感 数据 进行 特别 保护 ， 你 可 以 使 用 应 用 程序 无 法 直接 获取 的 密 铀 来 加 密 本 地 文 

件 。 例 如 ， 密 钥 可 以 存放 在 KeyStore 而 非 设备 上 ， 使 用 用 户 密码 进行 保护 。 尽 管 这 种 方式 无 
法 防止 通过 root 权 限 查 看 用 户 输入 的 密码 ， 但 是 它 可 以 为 未 进行 文件 系统 加 密 的 丢失 设备 提供 
保护 。 


使 用 外 部 存储 


创建 于 外 部 存储 的 文件 ， 比 如 SD 卡 ， 是 全 局 可 读 写 的 。 由 于 外 部 存储 器 可 被 用 户 移 除 并 且 能 
够 被 任何 应 用 修改 ， 因 此 不 应 使 用 外 部 存储 保存 应 用 的 敏感 信息 。 当 处 理 来 自 外 部 存储 的 数 
据 时 ， 应 用 程序 应 该 执行 输入 验证 (参看 输入 验证 章节 ) 我 们 强烈 建议 应 用 在 动态 加 载 之 前 
不 要 把 可 执行 文件 或 class 文 件 存 储 到 外 部 存储 中 。 如 果 一 个 应 用 从 外 部 存储 检索 可 执行 文 
件 ， 那 么 在 动态 加 载 之 前 它们 应 该 进行 签名 与 加 密 验 证 。 


使 用 Content Providers 


ContentProviders 提 供 了 一 种 结构 存储 机 制 ， 它 可 以 限制 你 自己 的 应 用 ， 也 可 以 允许 其 他 应 用 
程序 进行 访问 。 如 果 你 不 打算 向 其 他 应 用 提供 访问 你 的 ContentProvider 功 能 ， 那 么 在 
manifest 中 标记 他 们 为 android:exported=false 即 可 。 要 建立 一 个 给 其 他 应 用 使 用 的 
ContentProvider， 你 可 以 为 读 写 操作 指定 一 个 单一 的 permission， 或 者 在 manifest 中 为 读 写 操 
作 指 定 确切 的 权限 。 我 们 强烈 建议 你 对 要 分 配 的 权限 进行 限制 ， 仅 满足 目前 有 的 功能 即 可 。 
记 住 ， 通 常 新 的 权限 在 新 功能 加 入 的 时 候 同时 增加 ， 会 比 把 现 有 权限 撤销 并 打 断 已 经 存在 的 
用 户 更 合理 。 


如 果 Content Provider 仅 在 自己 的 应 用 中 共享 数据 ， 使 用 签名 级 别 android:protectionLevel 的 权 
限 是 更 可 取 的 。 签 名 权限 不 需要 用 户 确 认 ， 当 应 用 使 用 同样 的 密 钥 获取 数据 时 ， 这 提供 了 更 
好 的 用 户 体 验 ， 也 更 好 地 控制 了 Content Provider 数 据 的 访问 。Content Providers 也 可 以 通过 
声明 android:grantUriPermissions 并 在 触发 组 件 的 Intent 对 象 中 使 

用 FLAG_GRANT_READ_URI_PERMISSION 和 FLAG_GRANT_WRITE_URI_PERMISSION 
标志 提供 更 细致 的 访问 。 这 些许 可 的 作用 域 可 以 通过 grant-uri-permission 进 一 步 限 制 。 当 访 
问 一 个 ContentProvider 时 ， 使 用 参数 化 的 查询 方法 ， 比 如 query()，update() 和 delete() 来 避免 
来 自 不 信任 源 潜在 的 SQL 注入 。 注意 ， 如 果 Sselection 语 名 是 在 提交 给 方法 之 前 先 连接 用 户 数 
据 的 ， 使 用 参数 化 的 方法 或 许 不 够 。 不 要 对 "“ 写 "权限 有 一 个 错误 的 观念 。 考虑 “ 写 ” 权 限 允许 
Sql 语句 ， 它 可 以 通过 使 用 创造 性 的 WHERE 子 多 并 且 解 析 结 果 让 部 分 数据 的 确认 变 为 可 能 。 
例如 : 入 侵 者 可 能 在 通话 记录 中 通过 修改 一 条 记录 来 检测 某 个 特定 存在 的 电话 号 码 ， 只 要 那 
个 电话 号 码 已 经 存在 。 de XX content provider 数 据 有 可 预见 的 结构 ， 提 供 “ 写 "权限 也 许 等 同 于 
同时 提供 了 “ 读 写 ”权限 。 


使 用 权限 


因为 安 草 沙 盒 将 应 用 程序 隔离 ， 程 序 必 须 显 式 地 共享 资源 和 数据 。 它 们 通过 声明 他 们 需要 的 
权限 来 获取 额外 的 功能 ， 而 基本 的 沙 盒 不 提供 这 些 功 能 ， 比 如 相机 访问 设备 。 


请 求 权 限 


我 们 建议 最 小 化 应 用 请 求 的 权限 数量 ， 不 具有 访问 敏感 oum 这 些 
权限 的 风险 ， 可 以 增加 用 户 接受 度 ， 并 且 减 少 应 用 被 攻击 者 攻击 利用 的 可 能 性 。 


如 果 你 的 应 用 可 以 设计 成 不 需要 任何 权限 ， 那 最 好 不 过 。 例 如 : 与 其 请 求 访问 设备 信息 来 建 
立 一 个 标识 ， 不 如 建立 一 个 GUID 〈 这 个 例子 在 下 文 “ 处 理 用 户 数据 "中 有 说 明 ) o 


除了 请 求 权 限 之 外 ， 你 的 应 用 可 以 使 用 permissions 来 保护 可 能 会 暴露 给 其 他 应 用 的 安全 敏感 
的 IPC : 比如 ContentProvider。 通 常 来 说 ， 我 们 建议 使 用 访问 控制 而 不 是 用 户 权限 确认 许可 ， 
因为 权限 会 使 用 户 感 到 困惑 。 例 如 ， 考 虑 在 权限 设置 上 为 应 用 间 的 IPC 通 信使 用 单一 开发 者 提 
供 的 签名 保护 级 别 。 


不 要 泄 汤 受 许可 保护 的 数据 。 只 有 当 应 用 通过 |PC 暴 露 数 据 才 会 发 生 这 种 情况 ， 因 为 它 具 有 特 
殊 权限 ， 却 不 要 求 任何 客户 端的 IPC 接 口 有 那样 的 权限 。 更 多 关于 这 方面 的 潜在 影响 以 及 这 种 
问题 发 生 的 频率 在 USENIX: http://www.cs.be rkeley.edu/~afelt/felt_usenixsec2011.pdf 研 究 论 
文中 都 有 说 明 。 


创建 权限 


通常 ， 你 应 该 力求 建立 拥有 尽量 少 权 限 的 应 用 ， 直 至 满足 你 的 安全 需要 。 建 立 一 个 新 的 权限 
对 于 大 多 数 应 用 相对 少见 ， 因 为 系统 定义 的 许可 覆盖 很 多 情况 。 在 适当 的 地 方 使 用 已 经 存在 
的 许可 执行 访问 检查 。 


如 果 必 须 建 立 一 个 新 的 权限 ， 考 虑 能 否 使 用 signature protection level 来 完成 你 的 任务 。 签 名 
许可 对 用 户 是 透明 的 并 且 只 允许 相同 开发 者 签 a a een 
果 你 建立 一 个 dagerous protction level > PLAP ERREA 这 个 应 用 。 这 会 使 其 他 开 
发 者 困惑 ， 也 使 用 户 困 惑 。 


如 果 你 要 建立 一 个 危险 的 许可 ， 则 会 有 多 种 复杂 情况 需 考 虑 : 


e 对 于 用 户 将 要 做 出 的 安全 决定 ， 许 可 需要 用 字符 串 对 其 进行 简短 的 表述 。 
。 许可 字符 串 必 须 保 证 语言 的 国际 化 。 

e 用 户 可 能 对 一 个 许可 感到 困惑 或 者 知晓 风险 而 选择 不 安装 应 用 

e 当 许可 的 创造 者 未 安装 的 时 候 ， 应 用 可 能 要 求 许可 。 


上 面 每 一 个 因素 都 为 应 用 开发 者 带 来 了 重要 的 非 技 术 挑战 ， 同 时 也 使 用 户 感到 困惑 ， 这 也 是 
我 们 不 建议 使 用 危险 许可 的 原因 。 


使 用 网 络 


网 络 交易 具有 很 高 的 安全 风险 ， 因 为 它 涉 及 到 传送 私人 的 数据 。 人 们 对 移动 设备 的 隐私 关注 
日 益 加 深 ， 特别 是 当 设 备 进行 网 络 交易 时 ， 因 此 应 用 采取 最 佳 方 式 保护 用 户 数据 安全 极为 重 
要 。 


使 用 IP 网 络 


Android 下 的 网 络 与 Linux 环 境 下 的 差别 并 不 大 。 主 要 考虑 的 是 确保 对 敏感 数据 采用 了 适当 的 协 
议 ， 比 如 使 用 HTTPS 进 行 网 络 传输 。 我 们 在 任何 支持 HTTPS 的 服务 器 上 更 愿意 使 用 HTTPS 而 
不 是 HTTP， 因 为 移动 设备 可 能 会 频繁 连接 不 安全 的 网 络 ， 比 如 公共 WiFi 热 点 。 


授权 且 加 密 的 套 接 层级 别 的 通信 可 通过 使 用 SSLSocket 类 轻松 实现 。 考 虑 到 Android 设 备 使 用 
WiFi 连 接 不 安全 网 络 的 频率 ， 对 于 所 有 应 用 来 说 ， 使 用 安全 网 络 是 极力 鼓励 支持 的 。 


我 们 发 现 部 分 应 用 使 用 localhost 端 口 处 理 敏 感 的 IPC。 我 们 不 鼓励 这 种 方法 ， 是 因为 这 些 接口 
可 被 设备 上 的 其 他 应 用 访问 。 相 反 ， 你 应 该 在 可 认证 的 地 方 使 用 Android IPC 机 制 ， 例 如 
Service ( Ute RF] wl Xe 3e 18 83 E AR INADDR.. ANY > A A 4 85 Ez FE] T REIS] RA TETTE HA RAY 
请 求 ， 我 们 也 已 经 见识 过 了 ) 。 


一 个 有 必要 重复 的 常见 议题 是 ， 确 保 不 信任 从 HTTP 或 者 其 他 不 安全 协议 下 载 的 数据 。 这 包括 
在 WebView 中 的 输入 验证 和 对 于 http 的 任何 响应 。 


使 用 电话 网 络 


SMS 协 议 是 Android 开 发 者 使 用 最 频繁 的 电话 协议 ， 主 要 为 用 户 与 用 户 之 间 的 通信 设计 ， 但 对 
于 想 要 传送 数据 的 应 用 来 说 并 不 合适 。 由 于 SMS 的 限制 性 ， 我 们 强烈 建议 使 用 Google Cloud 
Messaging (GCM) 和 IP 网 络 从 web 服 务 器 发 送 数据 消息 给 用 户 设 备 应 用 。 


很 多 开发 者 没有 意识 到 SMS 在 网 络 上 或 者 设备 上 是 不 加 密 的 ， 也 没有 牢固 验证 。 特 别 是 任何 
SMS 接 收 者 应 该 预料 到 恶意 用 户 也 许 已 经 给 你 的 应 用 发 送 了 SMS : 不 要 指望 未 验证 的 SMS 数 
据 执 行 敏感 操作 。 你 也 应 该 注意 到 SMS 在 网 络 上 也 许 会 遵 到 冒名 顶替 并 且 / 或 者 拦截 ， 对 于 
Android 设 备 本 身 ，SMS 消 息 是 通过 广播 intent 传 递 的 ， 所 以 他 们 也 许 会 被 其 他 拥 

有 READ_SMS 许 可 的 应 用 截获 。 


输入 验证 


无 论 应 用 运行 在 什么 平台 上 ， 功 能 不 完善 的 输入 验证 是 最 常见 的 影响 应 用 安全 问题 之 一 。 
Android 有 平台 级 别 的 对 策 ， 用 于 减少 应 用 的 公开 输入 验证 问题 ， 你 应 该 在 可 能 的 地 方 使 用 这 
些 功能 。 同 样 需要 注意 的 是 ， 选 择 类 型 安全 的 语言 能 减少 输入 验证 问题 。 


如 果 你 使 用 native 代 码 ， 那 么 任何 从 文件 读 取 的 ， 通 过 网 络 接收 的 ， 或 者 通过 IPC 接 收 的 数据 
都 有 可 能 引发 安全 问题 。 最 常见 的 问题 是 buffer overflows > use after free， 和 off-by-one。 
Android 提 供 安 全 机 制 比如 ASLR 和 DEP 以 减少 这 些 漏 洞 的 可 利用 性 ， 但 是 没有 解决 基本 的 问 
题 。 小 心 处 理 指 针 和 管理 缓存 可 以 预防 这 些 问 题 。 


动态 、 基 于 字符 串 的 语言 ， 比 如 JavaScript 和 SQL ， 都 常 受到 由 转 义 字符 和 脚本 注入 带 来 的 输 
入 验证 问题 。 


如 果 你 使 用 提交 到 SQL Database 或 者 Content Provider 的 数据 ，SQL 注 入 也 许 是 个 问题 。 最 
好 的 防御 是 使 用 参数 化 的 查询 ， 就 像 ContentProviders 中 讨论 的 那样 。 限 制 权 限 为 只 读 或 者 只 
写 可 以 减少 SQL 注入 的 潜在 危害 。 


如 果 你 不 能 使 用 上 面 提 到 的 安全 ， 我 们 强烈 建议 使 用 结构 严谨 的 数据 格式 并 且 验 证 符合 
期 望 的 格式 。 黑 名 单 策 a. ， 但 这 些 技术 在 实践 中 是 多 错 的 并 且 当 错 
误 可 能 发 生 的 时 候 应 该 尽量 避免 。 


处 理 用 户 数据 


通常 来 说 ， 处 理 用 户 数据 安全 最 好 的 方法 是 最 小 化 获取 敏感 数据 用 户 个 人 数据 的 API 使 用 。 如 
果 你 对 数据 进行 访问 并 且 可 以 避免 存储 或 传输 ， 那 就 不 要 存储 和 传输 数据 。 最 后 ， 思 考 是 否 
有 一 种 应 用 逻辑 可 能 被 实现 为 使 用 hash 或 者 不 可 逆 形 式 的 数据 。 例 如 ， 你 的 应 用 也 许 使 用 一 
个 email 地 址 的 hash 作 为 主键 ， 避 免 传输 或 存储 email 地 址 ， 这 减少 无 意 间 泄漏 数据 的 机 会 ， 
并 且 也 能 减少 攻击 者 尝试 利用 你 的 应 用 的 机 会 。 


如 果 你 的 应 用 访问 私人 数据 ， 比 如 密码 或 者 用 户 名 ， 记 住 司法 也 许 要 求 你 提供 一 个 使 用 和 存 
储 这 些 数据 的 隐私 策略 的 解释 。 所 以 遵守 最 小 化 访问 用 户 数据 最 佳 的 安全 实践 也 许 只 是 简单 
的 服从 。 


你 也 应 该 考虑 到 应 用 是 否 会 疏忽 暴露 个 人 信息 给 其 他 方 ， 比 如 广告 第 三 方 组 件 或 者 你 应 用 使 
用 三 方 服务 。 如 果 你 不 知道 为 什么 一 个 组 件 或 者 服务 请 求 个 人 信息 ， 那 么 就 不 要 提供 给 
常 来 说 ， 通 过 减少 应 用 访问 个 人 信息 ， 会 减少 这 个 区 域 漆 在 的 问题 。 


如 果 必 须 访问 敏感 数据 ， 评 估 这 个 信息 是 否 必 须要 传 到 服务 器 ， 或 者 是 否 可 以 被 客户 ce 
作 。 考 虑 客户 端 上 使 用 敏感 数据 运行 的 任何 代码 ， 避 免 传 输 用 户 数 据 确保 不 会 无 意 问 通 

渡 自 由 的 IPC、world writable 文 件 、 或 网 络 socket 暴 露 用 户 数据 给 其 他 设备 上 的 应 用 。 ee 
一 个 泄漏 权限 保护 数据 的 特别 例子 ， 在 Requesting Permissions 3t Y Pit 7 © 
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相关 的 电话 号 码 或 者 IMEI。 这 个 话题 在 Android Developer Blog 中 有 更 详细 的 讨论 。 


应 用 开发 者 应 谨 懂 的 把 log 写 到 机 器 上 。 在 Android 中 ，log 是 共享 资源 ， 一 个 带 
A READ LOGS 许 可 的 应 用 可 以 访问 。 即 使 电话 log 数 据 是 临时 的 并 且 在 重启 之 后 会 擦 除 ， 不 
恰当 地 记录 用 户 信息 会 无 意 间 泄漏 用 户 数据 给 其 他 应 用 。 


使 用 WebView 


为 WebView 能 包含 HTML 和 JavaScript 浏 览 网 络 内 容 ， 不 恰当 的 使 用 会 引入 常见 的 web 安 全 
问题 ， 比 如 跨 站 脚本 攻击 〈JavaScript 注 入 ) ° dn we 
力 到 应 用 请 求 功 能 最 小 化 来 减少 这 些 潜在 的 问题 。 


如 果 你 的 应 用 没有 在 WebView 内 直接 使 用 JavaScript， 不 要 调用 setJavaScriptEnabled()。 某 
些 样本 代码 使 用 这 种 方法 ， 可 能 会 导致 在 产品 应 用 中 改变 用 途 : 所 以 如 果 不 需 要 的 话 移 除 
它 。 默 认 情 况 下 WebView 不 执行 JavaScript， 所 以 跨 站 脚本 攻击 不 会 产生 。 


使 用 addJavaScriptlnterface() 要 特别 的 小 心 ， 因 为 它 允 许 JavaScript 执 行 通常 保留 给 Android 
应 用 的 操作 。 只 把 addJavaScriptlnterface() 暴 露 给 可 靠 的 输入 源 。 如 果 不 受 信任 的 输入 是 被 允 
许 的 ， 不 受信 任 的 JavaScript 也 许 会 执行 Android 方 法 。 总 得 来 说 ， 我 们 建议 只 把 
addJavaScriptInterface() & $& 28-4 & Ff] P &, 2-85 JavaScript » 


如 果 你 的 应 用 通过 WebView 访 问 敏感 数据 ， 你 也 许 想 要 使 用 clearCache() 方 法 来 删除 任何 存储 
到 本 地 的 文件 。 服 务 端 的 header， 比 如 no-cache， 能 用 于 指示 应 用 不 应 该 缓存 特定 的 内 容 。 


ab SE TE P 


通常 来 说 ， 我 们 建议 请 求 用 户 证 书 频率 最 小 化 -- 使 得 钓鱼 攻击 更 明显 ， 并 且 降 低 其 成 功 的 可 
能 。 取 而 代 之 使 用 授权 令 牌 然后 刷新 它 。 


可 能 的 情况 下 ， 用 户 名 和 密码 不 应 该 存储 到 设备 上 ， 而 使 用 用 户 提供 的 用 户 名 和 密码 执行 初 
始 认证 ， 然 后 使 用 一 个 短暂 的 、 特 定 服务 的 授权 令 牌 。 可 以 被 多 个 应 用 访问 的 service 应 该 使 
用 AccountManager 访 问 。 如 果 可 能 的 话 ， 使 用 AccountManager 类 来 执行 基于 云 的 服务 并 且 
不 把 密码 存储 到 设备 上 。 


使 用 AccountManager 获 取 Account 之 后 ， 进 入 任何 证 书 前 检查 CREATOR， 这 样 你 就 不 会 因 
为 足 忽而 把 证 书 传 递 给 错误 的 应 用 。 


如 果 证 书 只 是 用 于 你 创建 的 应 用 ， 那 么 你 能 使 用 checkSignature() 验 证 访问 AccountManager 
的 应 用 。 或 者 ， 如 果 一 个 应 用 要 使 用 证 书 ， 你 可 以 使 用 KeyStore 来 储存 。 


使 用 加 窖 


除了 采取 数据 隔离 ， 支 持 完整 的 文件 系统 加 密 ， 提 供 安全 信道 之 外 。Android 提 供 大 量 加 密 算 
法 来 保护 数据 。 


通常 来 说 ， 尝 试 使 用 最 高 级 别 的 已 存在 framework 的 实现 来 支持 ， 如 果 你 需要 安全 的 从 一 个 已 
知 的 位 置 取 回 一 个 文件 ， 一 个 简单 的 HTTPS URI 也 许 就 足够 了 ， 并 且 这 部 分 不 要 求 任何 加 密 
知识 。 如 果 你 需要 一 个 安全 信道 ， 考 虑 使 用 HttpsURLConnection 或 者 SSLSocket 要 比 使 用 你 
自己 的 协议 好 。 


如 果 你 发 现 的 确 需要 实现 一 个 自 定义 的 协议 ， 我 们 强烈 建议 你 不 要 自己 实现 加 密 算 法 。 使 用 
已 经 存在 的 加 密 算 法 ， 比 如 Cipher 类 中 提供 的 AES 或 者 RSA。 


使 用 一 个 安全 的 随机 数 生 成 器 (SecureRandom) 来 初始 化 加 密 密 钥 (KeyGenerator) 。 使 
用 一 个 不 安全 随机 数 生成 器 生成 的 密 钥 严重 削弱 算法 的 优点 ， 而 且 可 能 遭 到 离线 攻击 。 


如 果 你 需要 存储 一 个 密 铀 来 重复 使 用 ， 使 用 类 似 于 KeySitore 的 机 制 ， 来 提供 长 期 储存 和 检索 
加 密 密 钥 的 功能 。 


一 些 Android 应 用 试图 使 用 传统 的 Linux 技 术 实 现 IPC， 比 如 网 络 socket 和 共享 文件 。 我 们 强烈 
鼓励 使 用 Android 系 统 IPC 功 能 ， 比 如 Intent，Binder > MAS ANGAN UNEAN ARREA o 
Android IPC 机 制 允 许 你 为 每 一 个 IPC 机 制 验证 连接 到 你 的 IPC 和 设置 安全 策略 的 应 用 的 身份 。 


很 多 安全 元 素 通 过 IPC 机 制 共 享 。Broadcast Receiver, Activitie, 和 Service 都 在 应 用 的 manifest 
中 声明 。 如 果 你 的 IPC 机 制 不 打算 给 其 他 应 用 使 用 ， 设 置 android:exported /&' 隆 为 false。 这 对 
于 同一 个 UID 内 包含 多 个 进程 的 应 用 ， 或 者 在 开发 后 期 决定 不 想 通 过 IPC 暴 露 功能 并 且 不 想 重 
写 代码 的 时 候 非常 有 用 。 


如 果 你 的 IPC 打 算 让 别 的 应 用 访问 ， 你 可 以 通过 使 用 Permission 标 记 设 置 一 个 安全 策略 。 如 果 
IPC 是 使 用 同一 个 密 钥 签名 的 独立 的 应 用 间 的 ， 使 用 signature 更 好 一 些 


使 用 Intent 


Intent 是 Android 中 异步 IPC 机 制 的 首选 。 根 据 你 应 用 的 需求 ， 你 也 许 使 
用 sendBroadcast()，sendOrderedBroadcast() 或 者 直接 的 intent 来 指定 一 个 应 用 组 件 。 


注意 ， 有 序 广播 可 以 被 Receiver 接 收 ， 所 以 他 们 也 许 不 会 被 发 送 到 PT AVES 中 。 如 果 你 要 
发 送 一 个 intent 给 指定 的 Receiver， 这 个 intent 必 须 被 直接 的 发 送 给 这 个 Receiver ° 


Intent 的 发 送 者 能 在 发 送 的 时 候 验 证 Receiver 是 否 有 一 个 许可 指定 了 一 个 non-Null 
Permission。 只 有 有 那个 许可 的 应 用 才 会 收 到 这 个 intent。 如 果 广 播 intent 内 的 数据 是 敏感 的 ， 
你 应 AR 用 没有 恰当 的 许可 无 法 注册 接收 那些 消息 。 这 种 情况 下 ， 
可 以 考虑 直接 执行 这 个 Receiver 而 不 是 发 起 一 个 广播 。 

注意 : Intent 过 滤器 不 能 作为 安全 特性 -- 组 件 可 被 intent 显 式 调 用 ， 可 能 会 没有 符合 intent 


过 滤器 的 数据 。 你 应 该 在 Intent Receiver 内 执行 输入 验证 ， 确 认 对 于 调用 Receiver ， 
Service、 或 Activity 来 说 格式 正确 合理 。 


使 用 服务 
Service 经 常 被 用 于 为 其 他 应 用 提供 服务 。 每 个 service 类 必须 在 它 的 manifest 文 件 进行 相应 的 
声 明 o 


默认 情况 下 ，Service 不 能 被 导出 和 被 其 他 应 用 执行 。 如 果 你 加 入 了 任何 Intent 过 滤器 到 
声明 中 ， 那 么 它 默 认为 可 以 被 导出 。 最 好 明确 声明 android:exported 元 素来 确定 它 按照 你 设想 

的 运行 。 可 以 使 用 android:permission 保 护 Service。 这 样 做 ， 其 他 应 用 在 他 们 自己 的 manifest 
文件 中 将 需要 声明 相应 的 元 素来 启动 、 停 止 或 者 绑 定 到 这 个 Service 上 。 


一 个 Service 可 以 使 用 许可 保护 单独 的 IPC 调 用 ， 在 执行 调用 前 通过 调 
用 checkCallingPermission() 来 实现 。 我 们 建议 使 用 manifest 中 声明 的 许可 ， 因 为 那些 是 不 容 
多 监管 的 。 


使 用 binder 和 messenger 接 口 


在 Android 中 ，Binders 和 Messenger 是 RPC 风 格 IPC 的 首选 机 制 。 必 要 的 话 ， 他 们 提供 一 个 定 
义 明确 的 接口 ， 促 进 彼 此 的 端点 认证 。 


我 们 强烈 鼓励 在 一 定 程度 上 ， 设 计 不 要 求 指定 许可 检查 的 接口 。Binder 和 Messenger 不 在 应 用 
的 manifest 中 声明 ， 因 此 你 不 能 直接 在 Binder 上 应 用 声明 的 许可 。 它 们 在 应 用 的 manifest 中 继 
承 许可 声明 ，Service 或 者 Activity 内 实现 了 许可 。 如 果 你 打算 创建 一 个 接口 ， 在 一 个 指定 
binder 接 口上 要 求 认 证 和 /或 者 访问 控制 ， 这 些 控制 必须 在 Binder 和 Messenger 的 接口 中 明确 添 
加 代码 。 


如 果 提 供 一 个 需要 访问 控制 的 接口 ， 使 用 checkCallingPermission() 来 验证 调用 者 是 否 拥 有 必 
要 的 许可 。 由 于 你 的 应 用 的 id 已 经 被 传递 到 别 的 接口 ， 因 此 代表 调用 者 访问 一 个 Service 之 前 
这 尤其 重要 。 如 果 调 用 一 个 Service 提 供 的 接口 ， 如 果 你 没有 对 给 定 的 Service 访 问 许 

可 ，bindService() 请 求 也 许 会 失败 。 如 果 调 用 你 自己 的 应 用 提供 的 本 地 接口 ， 使 

用 clearCallingldentity() 来 进行 内 部 安全 检查 是 有 用 的 。 


更 多 关于 用 服务 运行 I|PC 的 信息 ， 参 见 Bound Services 


利用 BroadcastReceiver 
Broadcast receivers 是 用 来 处 理 通过 intent 发 起 的 异步 请 求 。 


默认 情况 下 ，Receiver 是 导出 的 ， 并 且 可 以 被 任何 其 他 应 用 执行 。 如 果 你 的 
BroadcastReceiver 打 算 让 其 他 应 用 使 用 ， 你 也 许 想 在 应 用 的 manifest 文 件 中 使 用 元 素 对 
receiver 使 用 安全 许可 。 这 将 阻止 没有 恰当 许可 的 应 用 发 送 intent 给 这 个 BroadcastReceiver 。 


动态 加 载 代 码 


我 们 不 鼓励 从 应 用 文件 外 加 载 代码 。 考 虑 到 代码 注入 或 者 代码 篡改 ， 这 样 做 显著 增加 了 应 用 
暴露 的 可 能 ， 同 时 也 增加 了 版 本 管理 和 应 用 测试 的 复杂 性 。 最 终 可 能 造成 无 法 验证 应 用 的 行 
为 ， 因 此 在 某 些 环境 下 应 该 被 限制 。 

如 果 你 的 应 用 确实 动态 加 载 了 代码 ， 最 重要 的 事情 是 记 住 运行 动态 加 载 的 代码 与 应 用 具有 相 
同 的 安全 许可 。 用 户 决定 安装 你 的 应 用 是 基于 你 的 jd， 他 们 期 望 你 提供 任何 运行 在 应 用 内 部 的 
代码 ， 包 括 动态 加 载 的 代码 。 


动态 加 载 代码 主要 的 风险 在 于 代码 来 源 于 可 确认 的 源头 。 如果 这 个 模块 是 之 间 直 接 包含 在 你 
的 应 用 中 ， 那 么 它们 不 能 被 其 他 应 用 修改 ， 不 论 代码 是 本 地 库 或 者 是 使 用 DexClassLoader 加 
载 的 类 这 都 是 事实 。 我 们 见 过 很 多 应 用 实例 尝试 从 不 安全 的 地 方 加 载 代 码 ， 比 如 从 网 络 上 通 
过 非 加 密 的 协议 或 者 从 全 局 可 写 的 位 置 (比如 外 部 存储 ) 下 载 数 据 。 这 些 地 方 会 允许 网 络 上 
其 他 人 在 传输 过 程 中 修改 其 内 容 ， 或 者 允许 用 户 设备 上 的 其 他 应 用 修改 其 内 容 。 


在 虚拟 机 器 安全 性 


Dalvik 是 安 草 的 运行 时 虚拟 机 (VM)。Dalvik 是 特别 为 安 草 建立 的 ， 但 许多 其 他 虚拟 机 相关 的 安 
全 代码 的 也 适用 于 安 草 。 一 般 来 说 ， 你 不 应 该 关心 与 自己 有 关 的 虚拟 机 的 安全 问题 。 你 的 应 
用 程序 在 一 个 安全 的 沙 盒 环境 下 运行 ， 所 以 系统 上 的 其 他 进程 无 法 访问 你 的 代码 或 私人 数 
据 。 


如 果 你 想 更 深入 了 解 虚 拟 机 的 安全 问题 ， 我 们 建议 您 熟悉 一 些 现 有 文献 的 主题 。 推 荐 两 个 比 
较 流行 的 资源 : 


e http://www.securingjava.com/toc.html 
e https://www.owasp.org/index.php/Java Security Resources 


这 个 文档 集中 于 安 卓 与 其 他 VM 环境 不 同 地 方 。 对 于 有 在 其 他 环境 下 有 VM 编程 经 验 开发 者 来 
说 ， 这 里 有 两 个 普遍 的 问题 可 能 对 于 编写 Android 应 用 来 说 有 些 不 同 : 


e 一 些 虚 拟 机 ， 比 如 JVM 或 者 .Net， 担 任 一 个 安全 的 边界 作用 ， 代 码 与 底层 操作 系统 隔离 。 
在 Android 上 ，Dalvik VM 不 是 一 个 安全 边界 : 应 用 沙 箱 是 在 系统 级 别 实现 的 ， 所 以 Dalvik 
可 以 在 同一 个 应 用 与 native 代 码 相 互 操作 ， 没 有 任何 安全 约束 。 

e 已 知 的 手机 上 的 存储 限制 ， 对 来 发 者 来 说 ， 想 要 建立 模块 化 应 用 和 使 用 动态 类 加 载 是 很 
常见 的 。 要 这 么 做 的 时 候 需 要 考虑 两 个 资源 : 一 是 在 哪里 恢复 你 的 应 用 逻辑 ， 二 是 在 哪 
里 存储 它们 。 不 要 从 未 验证 的 资源 使 用 动态 类 加 载 器 ， 比 如 不 安全 的 网 络 资源 或 者 外 部 
存储 ， 因 为 那些 代码 可 能 被 修改 为 包含 恶意 行为 。 


本 地 代码 的 安全 


一 般 来 说 ， 对 于 大 多 数 应 用 开发 ， 我 们 鼓励 开发 者 使 用 Android SDK 而 不 是 使 用 [Android 
NDK] (http://developer.android.com/tools/sdk/ndk/index.html) 的 native 代 码 。 编 译 native 代 码 
的 应 用 更 为 复杂 ， 移 植 性 差 ， 更 容易 包含 常见 的 内 存 崩 演 错 误 ， 比 如 缓冲 区 溢出 。 


Android 使 用 Linux 内 核 编 译 并 且 与 Linux 开 发 相似 ， 如 果 你 打算 使 用 native 人 代码， 安全 策略 尤其 
有 用 。 与 Linux 有 关 的 安全 问题 超出 了 本 文 的 讨论 范围 ， 但 读者 可 以 参考 Secure Programming 
for Linux and Unix HOWTO 。 


与 大 多 数 Linux 环 境 的 一 个 重要 区 别 是 应 用 沙 箱 。 在 Android 中 ， 所 有 的 应 用 运行 在 应 用 沙 箱 
中 ， 包 括 用 native 代 码 编写 的 应 用 。 在 最 基本 的 级 别 中 ， 与 Linux 相 似 ， 对 于 开发 者 来 说 最 好 
的 方式 是 知道 每 个 应 用 被 分 配 一 个 权限 非常 有 限 的 唯一 UID。 这 里 讨论 的 比 Android Security 
Overview 中 更 细节 化 ， 你 应 该 熟悉 应 用 许可 ， 即 使 你 使 用 的 是 native 代 码 。 


使 用 HTTPS 与 SSL 


编写 :craftsmanBai - http://z1ng.net - 原文 : 
http://developer.android.com/training/articles/security-ssl.html 


SSL， 安 全 套 接 层 (TSL)， 是 一 个 常见 的 用 来 加 密 客户 端 和 服务 器 通信 的 模块 。 但 是 应 用 程序 
错误 地 使 用 SSL 可 能 会 导致 应 用 程序 的 数据 在 网 络 中 被 恶意 攻击 者 拦截 。 为 了 确保 这 种 情况 不 
在 我 们 的 应 用 中 发 生 ， 这 篇 文章 主要 说 明 使 用 网 络 安全 协议 常见 的 陷阱 和 使 用 Public-Key 
Infrastructure(PKN) 时 一 些 值得 关注 的 问题 。 


概念 


一 个 典型 的 SSL 使 用 场景 是 ， 服务器 配置 中 包含 了 一 个 证 书 ， 有 匹配 的 公 钥 和 私 钥 。 作 为 SSL 
客户 端 和 服务 端 握手 的 一 部 分 ， 服 务 端 通过 使 用 public-key cryptography( 公 和 钥 加 密 算 法 ) 进 行 
证 书签 名 来 证 明 它 有 私 钥 。 


然而 ， 任 何人 都 可 以 生成 他 们 自己 的 证 书 和 私 钥 ， 因 此 一 次 简单 的 握手 不 能 证 明 服务 端 具有 
匹配 证 书 公 铀 的 私 铀 。 一 种 解决 这 个 问题 的 方法 是 让 客户 端 拥有 一 套 或 者 更 多 可 信赖 的 证 
书 。 如 果 服 务 端 提供 的 证 书 不 在 其 中 ， 那 么 它 将 不 能 得 到 客户 端的 信任 。 


这 种 简单 的 方法 有 一 些 缺 陷 。 服 务 端 应 该 根据 时 间 升 级 到 强壮 的 密 钥 (key rotation)， 更 新 证 书 
中 的 公 钥 。 不 幸 的 是 ， 现 在 客户 端 应 用 需要 根据 服务 端 配置 的 变化 来 进行 更 新 。 如 果 服 务 端 
不 在 应 用 程序 开发 者 的 控制 下 ， 问 题 将 变 得 更 加 麻烦 ， 比 如 它 是 一 个 第 三 方 网 络 服 务 。 如 果 
程序 需要 和 任意 的 服务 器 进行 对 话 ， 例 如 Web 浏览 器 或 者 email 应 用 ， 这 种 方法 也 会 带 来 问 

题 。 


为 了 解决 这 个 问题 ， 服 务 端 通常 配置 了 知名 的 的 发 行者 证 书 ( 称 为 Certificate 
Authorities(CAs)。 提 供 的 平台 通常 包含 了 一 系列 知名 可 信赖 的 CAs © Android4.2(Jelly Bean) 
包含 了 超过 100CAs 并 在 每 个 发 行 版 中 更 新 。 和 服务 端 相似 的 是 ， 一 个 CA 拥有 一 个 证 书 和 一 
个 私 钥 。 当 为 一 个 服务 端 发 布 颁发 证 书 的 时 候 ，CA 用 它 的 私 钥 为 服务 端 签 名 。 客 户 端 可 以 通 
过 服务 端 拥有 被 已 知 平台 CA 签名 的 证 书 来 确认 服务 端 。 


然而 ， 使 用 CAS 又 带 来 了 其 他 的 问题 。 因 为 CA 为 许多 服务 端 证 书签 名 ， 你 仍然 需要 其 他 的 方 
法 来 确保 你 对 话 的 是 你 想 要 的 服务 器 。 为 了 解决 这 个 问题 ， 使 用 CA 签名 的 的 证 书 通过 特殊 的 
名 字 如 gmail.com 或 者 带 有 通配符 的 域名 如 *.google.com 来 确认 服务 端 。 下 面 这 个 例子 会 使 
这 些 概念 具体 化 一 些 。openss| 工 具 的 客户 端 命令 关注 Wikipedia 服 务 端 证 书信 息 。 端 口 为 

443 (默认 为 HTTPS) 。 这 条 命令 将 open s_client 的 输出 发 送 给 openssl x509， 根 据 X.509 
standard 格 式 化 证 书 中 的 内 容 。 特 别 的 是 ， 这 条 命令 需要 对 象 (subject) ， 包 含 服务 端 名 字 
fo BR A (issuer) 来 确认 CA。 


$ openssl s client -connect wikipedia.org:443 | openssl x509 -noout -subject -issuer 
subject- /serialNumber-sOrr2rKpMVP70Z6E9BT5reY008SJEdYv/C-US/0-* . wikipedia.org/OU-GTOS3 
314600/0U=See www.rapidssl.com/resources/cps (c)11/0U=Domain Control Validated - Rapid 
SSL(R)/CN=* .wikipedia.org 

issuer= /C=US/0=GeoTrust, Inc./CN=RapidSSL CA 


可 以 看 到 由 RapidSSL CA 令 发 给 匹配 *,wikipedia.org 的 服务 端 证 书 。 


一 个 HTTP 的 例子 
假设 我 们 有 一 个 知名 CA 颁发 证 书 的 web 服 务 器 ， 那 么 可 以 使 用 下 面 的 代码 发 送 一 个 安全 请 求 ; 


URL url = new URL("https://wikipedia.org"); 
URLConnection urlConnection - url.openConnection(); 
InputStream in = urlConnection.getInputStream(); 
copyInputStreamToOutputStream(in, System.out); 


是 的 ， 它 就 是 这 么 简单 。 如 果 我 们 想 要 修改 HTTP 的 请 求 ， 可 以 把 它 交 付 给 
HttpURLConnection。Android 关 于 HttpURLConnetcion 文 档 中 还 有 更 贴切 的 关于 怎样 去 处 理 
请 求 、 响 应 头 、posting 的 内 容 、cookies 管 理 、 使 用 代理 、 获 取 responses 等 例子 。 但 是 就 这 
些 确认 证 书 和 域名 的 细节 而 言 ，Android 框 架 已 经 通过 AP| 为 我 们 考虑 到 了 这 些 细节 。 下 面 是 
其 他 需要 关注 的 问题 。 


服务 器 普通 问题 的 验证 


假设 没有 从 getlnputStream() 收 到 内 容 ， 而 是 抛 出 了 一 个 异常 


javax.net.ssl.SSLHandshakeException: java.security.cert.CertPathValidatorException: Tr 
ust anchor for certification path not found. 

at org.apache.harmony.xnet.provider.jsse.OpenSSLSocketImpl.startHandshake(Open 
SSLSocketImpl.java:374) 

at libcore.net.http.HttpConnection.setupSecureSocket(HttpConnection.java:209) 

at libcore.net.http.HttpsURLConnectionImpl$HttpsEngine.makeSslConnection(Https 
URLConnectionImpl.java:478) 

at libcore.net.http.HttpsURLConnectionImpl$HttpsEngine.connect(HttpsURLConnect 
ionImpl.java:433) 

at libcore.net.http.HttpEngine.sendSocketRequest(HttpEngine.java:290) 

at libcore.net.http.HttpEngine.sendRequest (HttpEngine. java: 240) 

at libcore.net.http.HttpURLConnectionImpl.getResponse(HttpURLConnectionImpl.ja 
va: 282) 

at libcore.net.http.HttpURLConnectionImpl.getInputStream(HttpURLConnectionImpl 
.java:177) 

at libcore.net.http.HttpsURLConnectionImpl.getInputStream(HttpsURLConnectionIm 
pl.java:271) 


这 种 情况 发 生 的 原因 包括 : 
1. 颁 布 证 书 给 服务 器 的 CA 不 是 知名 的 。 
2. 服 务 器 证 书 不 是 CA 签名 的 而 是 自己 签名 的 。 


3. 服 务 器 配置 缺失 了 中 间 CA 


下 面 将 会 分 别 讨论 当 我 们 和 服务 器 安全 连接 时 如 何 去 解 决 这 些 问 是 


无 法 识别 十 书 机 构 


在 这 种 情况 中 ，SSLHandshakeException 姬 常 产生 的 原因 是 我 们 有 一 个 不 被 系统 信任 的 CA。 
可 能 是 我 们 的 证 书 来 源 于 新 CA 而 不 被 安 草 信任 ， 也 可 能 是 应 用 运行 版 本 较 老 没有 CA。 更 多 的 
时 候 ， 一 个 CA 不 知名 是 因为 它 不 是 公开 的 CA， 而 是 政府 ， 公 司 ， 教 育 机 构 等 组 织 私 有 的 。 


幸运 的 是 ， 我 们 可 以 让 HttpsSURLConnection 学 会 信任 特殊 的 CA。 过 程 可 能 会 让 人 感到 有 一 些 
费解 ， 下 面 这 个 例子 是 从 InputStream 中 获得 特殊 的 CA， 使 用 它 去 创建 一 个 密 钥 库 ， 用 来 创建 
和 初始 化 TrustManager。TrustManager 是 系统 用 来 验证 服务 器 证 书 的 ， 这 些 证 书 通过 使 

用 TrustManager 信 任 的 CA 和 密 钥 库 中 的 密 钥 创建 。 给 定 一 个 新 的 TrustManager， 下 面 这 个 
例子 初始 化 了 一 个 新 的 SSLContext， 提 供 了 ae een ， 我 们 可 以 ES ES B 
HttpsURLConnection 的 默认 SSLSocketFactory。 这 样 连接 时 会 使 用 我 们 的 CA 来 进行 证 书 验 
证 。 


下 面 是 一 个 华盛顿 的 大 学 的 组 织 性 的 CA 的 使 用 例子 


// Load CAs from an InputStream 
// (could be from a resource or ByteArrayInputStream or ...) 
CertificateFactory cf - CertificateFactory.getInstance("X.509"); 
// From https://www.washington.edu/itconnect/security/ca/load-der.crt 
InputStream caInput = new BufferedInputStream(new FileInputStream("load-der.crt")); 
Certificate ca; 
try { 

ca = cf.generateCertificate(caInput); 

System.out.println("ca-" + ((X509Certificate) ca).getSubjectDN()); 
} finally { 

caInput.close(); 


// Create a KeyStore containing our trusted CAs 

String keyStoreType = KeyStore.getDefaultType(); 
KeyStore keyStore = KeyStore.getInstance(keyStoreType); 
keyStore.load(null, null); 
keyStore.setCertificateEntry("ca", ca); 


// Create a TrustManager that trusts the CAs in our KeyStore 

String tmfAlgorithm = TrustManagerFactory.getDefaultAlgorithm(); 
TrustManagerFactory tmf = TrustManagerFactory.getInstance(tmfAlgorithm) ; 
tmf.init(keyStore); 


// Create an SSLContext that uses our TrustManager 
SSLContext context - SSLContext.getInstance("TLS"); 
context.init(null, tmf.getTrustManagers(), null); 


// Tell the URLConnection to use a SocketFactory from our SSLContext 
URL url = new URL("https://certs.cac.washington.edu/CAtest/"); 
HttpsURLConnection urlConnection - 
(HttpsURLConnection)url.openConnection(); 
urlConnection.setSSLSocketFactory(context.getSocketFactory()); 
InputStream in = urlConnection.getInputStream(); 
copyInputStreamToOutputStream(in, System.out); 


使 用 一 个 常用 的 了 解 你 CA 的 TrustManager， 系 统 可 以 确认 你 的 服务 器 证 书 来 自 于 一 个 可 信任 
的 发 行者 。 


注意 : 许多 网 站 会 提供 一 个 可 选 解决 方案 : 即 让 用 户 安装 一 个 无 用 的 TrustManager。 如 
果 你 这 样 做 还 不 如 不 加 密 通 讯 过 程 ， 加 为 任何 人 都 可以 在 从 Fwifi 热 点 下 ， 使 用 伪装 成 你 
的 服务 器 的 代理 发 送 你 的 用 户 流 量 ， 进 行 DNS 坎 骗 ， 来 攻击 你 的 用 户 。 mae 
记录 用 户 密 码 和 其 他 个 人 资料 。 这 种 方式 可 以 奏效 的 原因 是 因为 攻击 者 可 以 生成 一 个 
书 ， 并 且 缺 少 可 以 验证 该 证 书 是 否 来 自 受 信任 的 来 源 的 TrustManager。 你 nde 
任何 人 会 话 。 所 以 不 要 这 样 做 ， 即 使 是 暂时 性 的 也 不 行 。 除 非 你 能 始终 让 你 的 应 用 信任 
服务 器 证 书 的 签发 者 。 


自 签名 服务 器 证 书 


第 二 种 SSLHandshakeException 取 决 于 自 签名 证 书 ， 意 味 着 服务 器 就 是 它 自己 的 CA。 这 同 未 
知 证 书 权威 机 构 类 似 ， 因 此 你 同样 可 以 用 前 面部 分 中 提 到 的 方法 。 


你 可 以 创建 自己 的 TrustManager， 这 一 次 直接 信任 服务 器 证 书 。 将 应 用 于 证 书 直接 捆绑 会 有 
一 些 缺点 ， 不 过 我 们 依然 可 以 确保 其 安全 性 。 我 们 应 该 小 心 确保 我 们 的 自 签名 证 书 拥有 合适 

的 强 密 钥 。 到 2012 年 ， 一 个 65537 指 数位 且 一 年 到 期 的 2048 位 RSA 签 名 是 合理 的 。 当 轮换 密 
钥 时 ， 我 们 应 该 查看 权威 机 构 (比如 NIST) 的 建议 (recommendation) 来 了 解 哪 种 密 钥 是 合 
适 的 。 


央 少 中 间 人 证 书 颁发 机 构 


第 三 种 SSLHandshakeException 情 况 的 产生 于 缺少 中 间 CA。 大 多 数 公开 的 CA 不 直接 给 éd 
器 签名 。 相 反 ， 他 们 使 用 它们 主要 的 机 构 (简称 根 认证 机 构 ) 证 书 来 给 中 间 认 证 机 构 签名 ， 

em EM di 
证 机 构 ， 在 服务 器 证 书 (由 中 间 证 书 颁发 机 构 签名 ) 和 证 书 验证 者 (只 知道 根 认证 机 构 ) 之 

间 留 下 了 一 个 缺口 。 为 了 解决 这 个 问题 ， 服 务 器 并 不 在 SSL 握 手 的 过 程 中 只 向 客户 端 发 送 它 的 
证 书 ， 而 是 一 系列 的 从 服务 器 到 必 经 的 任何 中 间 机 构 到 达 根 认证 机 构 的 证 书 。 


下 面 是 一 个 mail.google.com 证 书 链 ， 以 openssls_client 命 令 显示 : 


$ openssl s client -connect mail.google.com:443 


Certificate chain 

© s:/C-US/ST-California/L-Mountain View/0=Google Inc/CN-mail.google.com 
i:/C-ZA/O-Thawte Consulting (Pty) Ltd./CN-Thawte SGC CA 

1 s:/C-ZA/O-Thawte Consulting (Pty) Ltd./CN-Thawte SGC CA 
i:/C-US/O-VeriSign, Inc./OU-Class 3 Public Primary Certification Authority 


这 里 显示 了 一 台 服 务 器 发 送 了 一 个 由 Thawte SGC CA 为 mail.google.com 颁 发 的 证 书 ，Thawte 
SGC CA 是 一 个 中 间 证 书 颁发 机 构 ，Thawte SGC CA 的 证 书 由 被 安 卓 信任 的 Verisign CAM 
发 。 然 而 ， 配 置 一 人 台 服 务 器 不 包括 中 间 证 书 机 构 是 不 常见 的 。 例 如 ， 一 台 服 务 器 导致 安 草 浏 
览 器 的 错误 和 应 用 的 异常 : 


$ openssl s client -connect egov.uscis.gov:443 


Certificate chain 
© s:/C-US/ST-District Of Columbia/L-Washington/O-U.S. Department of Homeland Security 
/OU-United States Citizenship and Immigration Services/OU-Terms of use at www.verisign 
.com/rpa (c)05/CN=egov.uscis.gov 

i:/C-US/O-VeriSign, Inc./OU-VeriSign Trust Network/OU-Terms of use at https://www.v 
erisign.com/rpa (c)10/CN-VeriSign Class 3 International Server CA - G3 


更 有 趣 的 是 ， 用 大 多 数 桌 面 浏览 器 访问 这 人 台 服 务 器 不 会 导致 类 似 于 完全 未 知 CA 的 或 者 自 签 

的 服务 器 证 书 导致 的 错误 。 这 是 因为 大 多 tp a 
构 。 一 旦 浏览 器 访问 并 且 从 一 个 网 站 了 解 到 的 一 个 中 间 证 书 机 构 ， 下 一 次 它 将 不 需要 中 间 证 
书 机 构 包 含 证 书 链 。 


一 些 站 点 会 有 意 让 用 来 提供 资源 服务 的 二 级 服务 器 像 上 述 所 述 的 那样 。 比 如 ， 他 们 可 能 会 让 
他 们 的 主 HTML 页面 用 一 台 拥 有 全 部 证 书 链 的 服务 器 来 提供 ， 但 是 像 图 片 ，CSS， 或 者 
JavaScript 等 这 样 的 资源 用 不 包含 CA 的 服务 器 来 提供 ， 以 此 节省 带宽 。 不 幸 的 是 ， 有 时 这 些 
服务 器 可 能 会 提供 一 个 在 应 用 中 调用 的 web 服 务 。 这 里 有 两 种 解决 这 些 问 题 的 方法 : 


e 配置 器 使 它 包 含 服务 器 链 中 的 中 间 证 书 颁发 机 构 


或 者 ， 像 对 待 不 知名 的 CA 一 样 对 待 中 间 CA， 并 且 创 建 一 个 TrustManager 来 直接 信任 
它 ， 就 像 在 前 两 节 中 做 的 那样 。 


验证 主机 名 第 见 问 题 


就 像 在 文章 开头 提 到 的 那样 ， 有 两 个 关键 的 部 分 来 确认 SSL 的 连接 。 第 一 个 是 确认 证 书 来 源 于 
信任 的 源 ， 这 也 是 前 一 个 部 分 关注 的 焦点 。 这 一 部 分 关注 第 二 部 分 : 确保 你 当前 对 话 的 服务 
器 有 正确 的 证 书 。 当 情况 不 是 这 样 时 ， 你 可 能 会 看 到 这 样 的 典型 错误 


java.io.IOException: Hostname 'example.com' was not verified 

at libcore.net.http.HttpConnection.verifySecureSocketHostname(HttpConnection.j 
ava:223) 

at libcore.net.http.HttpsURLConnectionImpl$HttpsEngine.connect(HttpsURLConnect 
ioniImpl.java:446) 

at libcore.net.http.HttpEngine.sendSocketRequest(HttpEngine.java:290) 

at libcore.net.http.HttpEngine.sendRequest (HttpEngine. java: 240) 

at libcore.net.http.HttpURLConnectionImpl.getResponse(HttpURLConnectionImpl.ja 
va: 282) 

at libcore.net.http.HttpURLConnectionImpl.getInputStream(HttpURLConnectionImpl 
.java:177) 

at libcore.net.http.HttpsURLConnectionImpl.getInputStream(HttpsURLConnectionIm 
pl.java:271) 


服务 器 配置 错误 可 能 会 导致 这 种 情况 发 生 。 服 务 器 配置 了 一 个 证 书 ， 这 个 证 书 没 有 匹配 的 你 
想 连接 的 服务 器 的 Subject 或 者 subject 可 选 的 命名 域 。 一 个 证 书 被 许多 不 同 的 服务 器 使 用 是 可 
能 的 。 上 比如， 使 用 openssl s client -connect google.com:443 |openssl x509 -text 查看 google 
证 书 ， 你 可 以 看 到 一 个 subject 支 持 google.con .youtube.com, *.android.com 或 者 其 他 的 。 这 
种 错误 只 会 发 生 在 你 所 连接 的 服务 器 名 称 没 有 被 证 书 列 为 可 接受 。 


不 幸 的 是 另外 一 种 原因 也 会 导致 这 种 情况 发 生 : 虚拟 化 服务 。 当 用 HTTP 同 时 拥有 一 个 以 上 主 
机 名 的 服务 器 共享 时 ，web 服 务 器 可 以 从 HTTP/1.1 请 求 中 找到 客户 端 需要 的 目标 主机 名 。 不 
行 的 是 ， 使 用 HTTPS 会 使 情况 变 得 复杂 ， 因 为 服务 器 必须 知道 在 发 现 HTTP 请 求 前 返回 哪 一 个 
证 书 。 为 了 解决 这 个 问题 ， 新 版 本 的 SSL， 特 别 是 TLSV.1.0 和 之 后 的 版 本 ， 支 持 服务 器 名 指 
示 (SNI)， 人 允许 SSL 客 户 端 为 服务 端 指定 目标 主机 名 ， 从 而 返回 正确 的 证 书 。 幸运 的 是 ， 从 安 
车 2.3 开 始 ，HttpsURLConnection 支 持 SNI。 不 幸 的 是 ，Apache HTTP 客 户 端 不 这 样 ， 这 也 是 
我 们 不 鼓励 用 它 的 原因 之 一 。 如 果 你 需要 支持 安 草 2.2 或 者 更 老 的 版 本 或 者 Apache HTTP 客 户 
端 ， 一 个 解决 方法 是 建立 一 个 可 选 的 虚拟 化 服务 并 且 使 用 特别 的 端口 ， 这 样 服务 端 就 能 够 清 
楚 该 返回 哪 一 个 证 书 。 


采用 不 使 用 你 的 虚拟 服务 的 主机 名 HostnameVerifier 而 不 是 服务 器 默认 的 来 蔡 换 ， 是 很 重要 的 
选择 。 


注意 : 替换 HostnameVerifier 可 能 会 非常 危险 ， 如 果 另 外 一 个 虚拟 服务 不 在 你 的 控制 下 ， 中 间 
人 攻击 可 能 会 直接 使 流量 到 达 另 外 一 台 服 务 器 而 超出 你 的 预想 。 WRI RBM EE 
机 名 验证 ， 这 里 有 一 个 为 单 URLConnection 替 换 验 证 过 程 的 例子 : 


// Create an HostnameVerifier that hardwires the expected hostname. 
// Note that is different than the URL's hostname: 
// example.com versus example.org 
HostnameVerifier hostnameVerifier = new HostnameVerifier() { 
@Override 
public boolean verify(String hostname, SSLSession session) { 
HostnameVerifier hv = 
HttpsURLConnection.getDefaultHostnameVerifier(); 
return hv.verify("example.com", session); 


H 


// Tell the URLConnection to use our HostnameVerifier 
URL url - new URL("https://example.org/"); 
HttpsURLConnection urlConnection - 
(HttpsURLConnection)url.openConnection(); 
urlConnection.setHostnameVerifier(hostnameVerifier); 
InputStream in = urlConnection.getInputStream(); 
copyInputStreamToOutputStream(in, System.out); 


但 是 请 记 住 ， 如 果 你 发 现 你 在 替换 主机 名 验证 ， 特 别 是 庶 拟 服务 ， 另 外 一 个 虚拟 主机 不 在 你 
的 控制 的 情况 是 非常 危险 的 ， 你 应 该 找到 一 个 避免 这 种 问题 产生 的 托管 管理 。 


关于 直接 使 用 SSL Socket 的 警告 


到 目前 为 止 ， 这 些 例子 聚焦 于 使 用 HttpsURLConnection 上 。 有 时 一 些 应 用 需要 让 SSL 和 HTTP 
分 开 。 举 个 例子 ， 一 个 email 应 用 可 能 会 使 用 SSL 的 变种 ，SMTPPOP3,IMAP 等 。 在 那些 例子 
中 ， 应 用 程序 会 想 使 用 SSLSocket 直 接连 接 ， 与 HttpsSURLConnection 做 的 方法 相似 。 这 种 技 
术 到 目前 为 止 处 理 了 证 书 验证 问题 ， 也 应 用 于 SSLSocket 中 。 事 实 上 ， 当 使 用 常规 的 
TrustManager 时 ， 传 递 给 HttpsURLConnection 的 是 SSLSocketFactory。 如 果 你 需要 一 个 带 常 
规 的 SSLSocket 的 TrustManager， 采 取 下 面 的 步骤 使 用 SSLSocketFactory 来 创建 你 的 
SSLSocket ° 


注意 : SSLSocket 不 具有 主机 名 验证 功能 。 a 于 它 自己 的 主机 名 验证 ， 通 过 传 入 预 


期 的 主机 名 调用 getDefaultHostNameVerifier()) ° ad 要 注意 的 是 ， 当 发 生 错 误 
时 ，HostnameVerifier.verify() 不 知道 is BAR” fa EUR TI— Pn ` 值 ， 你 需要 进一步 明 
确 的 检查 。 下 面 是 一 个 演示 的 方法 。 这 个 例子 演 uei nanc 4433% 0 3E ELA 


有 SNI 支 持 的 时 候 ， 你 将 i o 你 需要 确保 证 书 的 确 是 


mail.google.com 的 。 


// Open SSLSocket directly to gmail.com 

SocketFactory sf - SSLSocketFactory.getDefault(); 

SSLSocket socket - (SSLSocket) sf.createSocket("gmail.com", 443); 
HostnameVerifier hv - HttpsURLConnection.getDefaultHostnameVerifier(); 
SSLSession s = socket.getSession(); 


// Verify that the certicate hostname is for mail.google.com 
// This is due to lack of SNI support in the current SSLSocket. 
if (!hv.verify("mail.google.com", s)) { 
throw new SSLHandshakeException("Expected mail.google.com, 
"found " + s.getPeerPrincipal()); 


} 


// At this point SSLSocket performed certificate verificaiton and 
// we have performed hostname verification, so it is safe to proceed. 


// ... use socket ... 
socket.close(); 


墨 名 单 


SSL 主要 依靠 CA 来 确认 证 书 来 自 正确 无 误 服务 器 和 域名 的 所 有 者 。 少 数 情况 下 ，CA 被 坎 骗 ， 
或 者 在 Comodo 和 DigiNotar 的 例子 中 ， 一 个 主机 名 的 证 书 被 颁发 给 了 除了 服务 器 和 域名 的 拥 
有 者 之 外 的 人 ， 导 致 被 破坏 。 


为 了 减少 这 种 危险 ， 安 章 可 以 将 一 些 黑 名 单 或 者 整个 CA 列 入 黑 名 音 。 尽 管 名 单 是 以 前 是 谋 入 
操作 系统 的 ， 从 安 卓 4.2 开 始 ， 这 个 名 单 在 以 后 的 方案 中 可 以 远程 更 新 。 


Ug s 


一 个 应 用 可 以 通过 阻塞 技术 保护 它 自己 免 于 受 虚 假 证 书 的 欺骗 。 这 是 简单 运用 使 用 未 知 CA 的 
例子 ， 限 制 应 OA 用 使 用 的 服务 器 。 阻 止 了 来 自 系统 中 另外 一 百 多 个 CA 的 
欺骗 而 导致 的 应 用 安全 通道 的 破坏 。 


客户 端 验 证 


这 篇 文章 聚焦 在 SSL 的 使 用 者 同 服务 器 的 安全 对 话 上 。SSL 也 支持 服务 端 通过 验证 客户 端的 证 
书 来 确认 客户 端的 身份 。 这 种 技术 也 与 TrustManager 的 特性 相似 。 可 以 参考 
在 HttpsURLConnection 文 档 中 关于 创建 一 个 常规 的 KeyManager 的 讨论 。 


nogotofail : 网 络 流量 安全 测试 工具 


对 于 已 知 的 TLS /ASSL 漏 河和 错误 ，nogotofail 提 供 了 一 个 简单 的 方法 来 确认 你 的 应 用 程序 是 
安全 的 。 它 是 一 个 自动 化 的 、 强 大 的 、 用 于 测试 网 络 的 安全 问题 可 扩展 性 的 工具 ， 任 何 设备 
的 网 络 流量 都 可 以 通过 它 o nogotofail 主 要 应 用 于 三 种 场景 

e 发 现 错误 和 漏洞 。 

e 验证 修补 程序 和 等 待 回归 。 

e 了 解 应 用 程序 和 设备 产生 的 交通 


nogotofail 可 以 工作 在 Android，iOS，Linux，Windows，Chrome OS，OSX 环 境 下 ， 事 实 上 
任何 需要 连接 到 Internet 的 设备 都 可 以 。Android 和 Linux 环 境 下 有 简单 易 用 获取 通知 的 客户 端 
配置 设置 ， 以 及 本 身 可 以 作为 靶 机 ， 部 署 为 一 个 路 由 器 ，VPN 服 务 器 ， 或 代理 。 你 可 以 在 
nogotofail 开 源 项 目 访问 该 工具 。 


更 新 你 的 Security Provider 来 对 抗 SSL 漏 洞 利 
用 


编写 :craftsmanBai - http://z1ng.net - 原文 : 
http://developer.android.com/training/articles/security-gms-provider.html 


Zik 3E security provider 保 障 网 络 通信 安全 。 然 而 有 时 默认 的 security provider 存 在 安全 漏 
洞 。 为 了 防止 这 些 漏洞 被 利用 ，Google Play services 提供 了 一 个 自动 更 新 设备 的 Security 
provider 的 方法 来 对 抗 已 知 的 漏洞 。 通 过 调用 Google Play services 方 法 ， 可 以 确保 你 的 应 用 
运行 在 可 以 抵抗 已 知 漏洞 的 设备 上 。 


举 个 例子 ，OpenSSL 的 漏洞 (CVE-2014-0224) 会 导致 中 间 人 攻击 ， 在 通信 双方 不 知情 的 情况 
下 解密 流量 。Google Play services 5.0 提 供 了 一 个 补丁 ， 但 是 必须 确保 应 用 安装 了 这 个 补 

丁 。 通 过 调用 Google Play services 方 法 ， 可 以 确保 你 的 应 用 运行 在 可 抵抗 攻击 的 安全 设备 
Ee 


注意 : 更 新 设备 的 security provider 不 是 更 新 android.net.SSLCertificateSocketFactory. 比 起 使 
用 这 个 类 ， 我 们 更 鼓励 应 用 开发 者 使 用 融入 密码 学 的 高 级 方法 。 大 多 数 应 用 可 以 使 用 类 

4A HttpsURL Connection > HttpClient ，AndroidHttpClient 这 样 的 APl， 而 不 必 去 设 

置 TrustManager 或 者 创建 一 个 SSLCertificateSocketFactory ° 


使 用 Providerlnstaller 给 Security Provider 打 补丁 


使 用 providerinstaller 类 来 更 新 设备 的 security provider。 你 可 以 通过 调用 该 类 的 方法 
installlfNeeded()( 或 者 installifneededasync) 来 验证 security provider 是 否 为 最 新 的 (必要 的 话 更 
ru) 


当 你 调用 installifneeded 时 ，providerinstaller 会 做 以 下 事情 : 
e 如 果 设 备 的 Provider 成 功 更 新 (或 已 经 是 最 新 的 )， 该 方法 返回 正常 。 


e 如 果 设 备 的 Google Play services 库 已 经 过 时 了 ， 这 个 方法 抛 出 
googleplayservicesrepairableexception 异 常 表明 无 法 更 新 Provider。 应 用 程序 可 以 捕获 
这 个 异常 并 向 用 户 弹 出 合适 的 对 话 框 提示 更 新 Google Play services 。 


e 如 果 产 生 了 不 可 恢复 的 错误 ， 该 方法 抛 出 googleplayservicesnotavailableexception 表 示 
它 无 法 更 新 Provider。 应 用 程序 可 以 捕获 异常 并 选择 合适 的 行动 ， 如 显示 标准 问题 解决 流 
FR o 

installifneededasync 方 法 类 似 ， 但 它 不 抛 出 异常 ， 而 是 通过 相应 的 回调 方法 ， 以 提示 成 功 或 
失败 。 


如 果 installifneeded 需 要 安装 一 个 新 的 Provider， 可 能 耗费 30-50 毫 秒 ( 较 新 的 设备 ) 到 350 毫 
秒 〈 昌 设备 ) 。 如 果 security provider 已 经 是 最 新 的 ， 该 方法 需要 的 时 间 量 可 以 忽略 不 计 。 为 
了 避免 影响 用 户 体 验 : 


e 线程 加 载 后 立即 在 后 台 网 络 线程 中 调用 installifneeded， 而 不 是 等 待 线 程 尝 试 使 用 网 络 。 
(多 次 调用 该 方法 没有 害处 ， 如 果 安 全 提供 程序 不 需要 更 新 它 会 立即 返回 。) 





e 如 果 用 户 体验 会 受 线程 阻塞 的 影响 比如 从 UI 线 程 中 调用 ， 那 么 使 
用 installifneededasync() 调 用 该 方法 的 异步 版 本 。 (当然 ， 如 果 你 要 这 样 做 ， 在 尝试 任何 
安全 通信 之 前 必须 等 待 操作 完成 。providerinstaller 调 用 监听 者 的 onproviderinstalled() 方 
法 发 出 成 功 信号 。 


警告 : 如 果 providerinstaller 无 法 安装 更 新 Provider， 您 的 设备 security provider 会 容 钨 受到 已 
知 漏洞 的 攻击 。 你 的 程序 等 同 于 所 有 HTTP 通 信 未 被 加 密 。 一 旦 Provider 更 新 ， 所 有 安全 
API (包括 SSL API) 的 调用 会 经 过 它 (但 这 并 不 适用 于 
android.net.sslcertificatesocketfactory， 面 对 cve-2014-0224 这 种 漏洞 仍然 是 脆弱 的 ) o 


同步 修补 


修补 security provider 最 简单 的 方法 就 是 调用 同步 方法 installlfNeeded(). 如 果 用 户 体验 不 会 被 线 
程 阻塞 影响 的 话 ， 这 种 方法 很 合适 。 


举 个 例子 ， 这 里 有 一 个 sync adapter 会 更 新 security provider。 由 于 它 运 行 在 后 台 ， 因 此 在 等 
待 security provider 更 新 的 时 候 线程 阻塞 是 可 以 的 。sync adapter 调 用 installifneeded() 更 新 
security provider。 如 果 返 回 正常 ，sync adapter 可 以 确保 security provider 是 最 新 的 。 如 果 返 
回 异 常 ，sync adapter 可 以 采取 适当 的 行动 (如 提示 用 户 更 新 Google Play services) 。 


HE 
* Sample sync adapter using {@link ProviderInstaller}. 
a 
public class SyncAdapter extends AbstractThreadedSyncAdapter { 


// This is called each time a sync is attempted; this is okay, since the 
// overhead is negligible if the security provider is up-to-date. 
@Override 
public void onPerformSync(Account account, Bundle extras, String authority, 
ContentProviderClient provider, SyncResult syncResult) { 
try { 
ProviderInstaller.installIfNeeded(getContext()); 
} catch (GooglePlayServicesRepairableException e) ( 


// Indicates that Google Play services is out of date, disabled, etc. 


// Prompt the user to install/update/enable Google Play services. 
GooglePlayServicesUtil.showErrorNotification( 
e.getConnectionStatusCode(), getContext()); 


// Notify the SyncManager that a soft error occurred. 
syncResult.stats.numIOExceptions--*; 
rrecuns 


) catch (GooglePlayServicesNotAvailableException e) { 
// Indicates a non-recoverable error; the ProviderInstaller is not able 
// to install an up-to-date Provider. 


// Notify the SyncManager that a hard error occurred. 
syncResult.stats.numAuthExceptions++; 
return; 


// If this is reached, you know that the provider was already up-to-date, 


// or was successfully updated. 


更 新 Security provider 可 能 耗费 350 毫 秒 ( 旧 设备 ) 。 如 果 在 一 个 会 直接 影响 用 户 体验 的 线程 
中 更 新 ， 如 UI 线 程 ， 那 么 你 不 会 希望 进行 同步 更 新 ， 因 为 这 可 能 导致 应 用 程序 或 设备 冻结 直 
到 操作 完成 。 因 此 你 应 该 使 用 异步 方法 installifneededasync()。 方 法 通过 调用 回调 函数 来 反馈 
其 成 功 或 失败 。 例如， 下 面 是 一 些 关于 更 新 security provider 在 UI 线程 中 的 活动 的 代码 。 调 用 
installifneededasync() 来 更 新 security provider， 并 指定 自己 为 监听 器 接收 成 功 或 失败 的 通 
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防止 SSL 漏 洞 而 更 新 Security 


知 。 如 果 security provider 是 最 新 的 或 更 新 成 功 ， 会 调用 onproviderinstalled() 方 法 ， een 
通信 是 安全 的 。 如 果 security provider 无 法 更 新 ， 会 调用 onproviderinstallfailed() 方 法 ， 并 采 
适当 的 行动 (如 提示 用 户 更 新 Google Play services ) 


PE 
* Sample activity using {@link ProviderInstaller}. 
if 
public class MainActivity extends Activity 
implements ProviderInstaller.ProviderInstallListener { 


private static final int ERROR_DIALOG_REQUEST_CODE = 1; 
private boolean mRetryProviderInstall; 


//Update the security provider when the activity is created. 
@Override 
protected void onCreate(Bundle savedInstanceState) { 
super .onCreate(savedInstanceState) ; 
ProviderInstaller.installIfNeededAsync(this, this); 


/** 
* This method is only called if the provider is successfully updated 
(or is already up-to-date). 
ud 
@Override 
protected void onProviderInstalled() { 
// Provider is up-to-date, app can make secure network calls. 


Jee 
* This method is called if updating fails; the error code indicates 
* whether the error is recoverable. 
oi 

@Override 

protected void onProviderInstallFailed(int errorCode, Intent recoveryIntent) { 

if (GooglePlayServicesUtil.isUserRecoverableError(errorCode)) { 
// Recoverable error. Show a dialog prompting the user to 
// install/update/enable Google Play services. 
GooglePlayServicesUtil.showErrorDialogFragment( 
errorCode, 
tel psy 
ERROR DIALOG REQUEST CODE, 
new DialogInterface.OnCancelListener() { 
@Override 
public void onCancel(DialogInterface dialog) { 
// The user chose not to take the recovery action 
onProviderInstallerNotAvailable(); 
} 
}); 
} else { 
// Google Play services is not available. 
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为 防止 SSL 漏 洞 而 更 新 Security 


onProviderInstallerNotAvailable(); 


@Override 
protected void onActivityResult(int requestCode, int resultCode, 
Intent data) { 
super.onActivityResult(requestCode, resultCode, data); 
if (requestCode == ERROR_DIALOG_REQUEST_CODE) { 
// Adding a fragment via GooglePlayServicesUtil.showErrorDialogFragment 
// before the instance state is restored throws an error. So instead, 
// set a flag here, which will cause the fragment to delay until 
// onPostResume. 
mRetryProviderInstall - true; 


Jee 
* On resume, check to see if we flagged that we need to reinstall the 
* provider. 

274 
@Override 
protected void onPostResume() { 
super.onPostResult(); 
if (mRetryProviderInstall) { 
// We can now safely retry installation. 
ProviderInstall.installIfNeededAsync(this, this); 
} 


mRetryProviderInstall = false; 


private void onProviderInstallerNotAvailable() { 
// This is reached if the provider cannot be updated for some reason. 
// App should consider all HTTP communication to be vulnerable, and take 
// appropriate action. 
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使 用 设备 管理 策略 增强 安全 性 


编写 :craftsmanBai - http://z1ng.net - 原文 : 
http://developer.android.com/training/enterprise/device-management-policy.html 


Android 2.2(API Level 8) 之 后 ，Android 平 台 通 过 设备 管理 API 提 供 系 统 级 的 设备 管理 能 力 。 


在 这 一 小 节 中 ， 你 将 学 到 如 何 通过 使 用 设备 管理 策略 创建 安全 敏感 的 应 用 程序 。 比 如 某 应 用 
可 被 配置 为 : 在 给 用 户 显 示 受 保护 的 内 容 之 前 ， 确 保 已 设置 一 个 足够 强度 的 锁 屏 密码 。 


定义 并 声明 你 的 策略 


首先 ， 你 需要 定义 多 种 在 功能 层面 提供 支持 的 策略 。 这 些 策略 可 以 包括 屏幕 锁 密 码 强度 、 密 
码 过 期 时 间 以 及 加 密 等 等 方面 。 


你 须 在 res/xml/device_admin.xml 中 声明 选择 的 策略 集 ， 它 将 被 应 用 强制 实行 。 在 Android 
manifest 也 需要 引用 声明 的 策略 集 。 


每 个 声明 的 策略 对 应 DevicePolicyManager 中 一 些 相 关 设备 的 策略 方法 (例如 定义 最 小 密码 长 
度 或 最 少 大 写字 母 字符 数 ) 。 如 果 一 个 应 用 尝试 调用 XML 中 没有 对 应 策略 的 方法 ， 程 序 在 会 
运行 时 抛 出 一 个 SecurityException 蜡 常 。 


如 果 应 用 程序 试图 管理 其 他 策略 ， 那 么 强制 锁 force-lock 之 类 的 其 他 权限 就 会 发 挥 作 用 。 正 如 
你 将 看 到 的 , 作为 设备 管理 权限 激活 过 程 的 一 部 分 , PB 8j] 策略 的 列表 会 在 系统 屏幕 上 显示 给 
用 户 。 如 下 代码 片段 在 res/xml/device_admin.xml 中 声明 了 密码 限制 策略 : 


«device-admin xmlns:android="http://schemas.android.com/apk/res/android"> 
<uses-policies> 
<limit-password /> 
</uses-policies> 
</device-admin> 


Æ Android manifest 引 用 XML 策略 声明 : 


«receiver android:name=".Policy$PolicyAdmin" 
android: permission="android.permission.BIND_DEVICE_ADMIN"> 
<meta-data android:name="android.app.device_admin" 
android: resource="@xml/device_admin" /> 
<intent-filter> 
<action android:name="android.app.action.DEVICE_ADMIN_ENABLED" /> 
</intent-filter> 
</receiver> 


创建 一 个 设备 管理 接受 端 


创建 一 个 设备 管理 广播 接收 端 (broadcast receiver) ， 可 以 接收 到 与 你 声明 的 策略 有 关 的 事 
件 通 知 。 也 可 以 对 应 用 程序 有 选择 地 重 写 回调 函数 。 


在 同样 的 应 用 程序 (Device Admin) 中 ， 当 设备 管理 (device administrator) 权限 被 用 户 设 
为 禁用 时 ， 已 配置 好 的 策略 就 会 从 共享 偏好 设置 (shared preference) 中 擦 除 。 


你 应 该 考虑 实现 与 你 的 应 用 业务 逻辑 相关 的 策略 。 例 如 ， 你 的 应 用 可 以 采取 一 些 措施 来 降低 
安全 风险 ， 如 : 删除 设备 上 的 敏感 数据 ， 禁 用 远程 同步 ， 对 管理 员 的 通知 提醒 等 等 。 


为 了 让 广播 接收 端 能 够 正常 工作 ， 请 务必 在 Android manifest 中 注册 下 面 代码 片段 所 示 内 容 。 


«receiver android:name=".Policy$PolicyAdmin" 
android: permission="android.permission.BIND_DEVICE_ADMIN"> 
<meta-data android:name="android.app.device_admin" 
android: resource="@xml/device_admin" /> 
<intent-filter> 


<action android:name="android.app.action.DEVICE_ADMIN_ENABLED" /> 
</intent-filter> 
</receiver> 


M 2 ` A eua 
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在 执行 任何 策略 之 前 ， 用 户 需 要 手动 将 程序 激活 为 具有 设备 管理 权限 ， 下 面 的 程序 片段 显示 
了 如 何 触 发 设置 框 以 便 让 用 户 为 你 的 程序 激活 权限 。 


通过 指定 EXTRA_ADD_EXPLANATION 给 出 明确 的 说 明 信 息 ， 以 告知 用 户 为 应 用 程序 激活 设 
备 管理 权限 的 好 处 。 


if (!mPolicy.isAdminActive()) { 


Intent activateDeviceAdminIntent - 


new Intent(DevicePolicyManager.ACTION ADD DEVICE ADMIN); 


activateDeviceAdminIntent.putExtra( 


DevicePolicyManager.EXTRA DEVICE ADMIN, 
mPolicy.getPolicyAdmin()); 


activateDeviceAdminIntent.putExtra( 
DevicePolicyManager.EXTRA ADD EXPLANATION, 


getResources().getString(R.string.device admin activation message)); 


startActivityForResult(activateDeviceAdminIntent, 
REQ ACTIVATE DEVICE ADMIN); 


Set password rules 
Control the length and t 


he 





Activate Cancel 


如 果 用 户 选 择 "Activate"， 程 序 就 会 获取 设备 管理 员 权 限 并 可 以 开始 配置 和 执行 策略 。 当然 ， 
程序 也 需要 做 好 处 理 用 户 选择 放弃 激活 的 准备 ， 比 如 用 户 点 击 了 “取消 "按钮 ， 返 回 键 或 者 
HOME 键 的 情况 。 因 此 ， 如 果 有 必要 的 话 ， 策 略 设置 中 的 onResume 人 方法 需要 加 入 重新 评估 
的 逻辑 判断 代码 ， 以 便 将 设备 管理 激活 选项 展示 给 用 户 。 


实施 设备 策略 控制 


在 设备 管理 权限 成 功 激活 后 ， 程 序 就 会 根据 请 求 的 策略 来 配置 设备 策略 管理 器 。 要 牢记 ， 新 
策略 会 被 添加 到 每 个 版 本 的 Android 中 。 所 以 你 需要 在 程序 中 做 好 平台 版 本 的 检测 ， 以 便 新 策 
略 能 被 老 版 本 平台 很 好 的 支持 。 例 如 ， "密码 中 含有 的 最 少 大 写字 符 数 "这 个 安全 策略 只 有 在 高 
于 API Level 11 (Honeycomb) 的 平台 才 被 支持 ， 以 下 代码 则 演示 了 如 何在 运行 时 检查 版 本 : 


DevicePolicyManager mDPM = (DevicePolicyManager ) 
context.getSystemService(Context.DEVICE POLICY SERVICE); 
ComponentName mPolicyAdmin - new ComponentName(context, PolicyAdmin.class); 


mDPM.setPasswordQuality(mPolicyAdmin, PASSWORD QUALITY VALUES [mPasswordQuality]); 

mDPM.setPasswordMinimumLength(mPolicyAdmin, mPasswordLength); 

if (Build.VERSION.SDK INT >= Build.VERSION CODES.HONEYCOMB) { 
mDPM.setPasswordMinimumUpperCase(mPolicyAdmin, mPasswordMinUpperCase) ; 


这 样 程序 就 可 以 执行 策略 了 。 当 程序 无 法 访问 正确 的 锁 屏 密码 的 时 候 ， 通 过 设备 策略 管理 器 

(Device Policy Manager) API 可 以 判断 当前 密码 是 否 适用 于 请 求 的 策略 。 如 果 当 前 锁 屏 密码 
满足 策略 ， 设 备 管理 API 不 会 采取 纠正 措施 。 明 确 地 启动 设置 程序 中 的 系统 密码 更 改 界面 是 应 
用 程序 的 责任 。 例 如 : 


if (!mDPM.isActivePasswordSufficient()) 1 


// Triggers password change screen in Settings. 
Intent intent - 

new Intent(DevicePolicyManager.ACTION SET NEW PASSWORD); 
startActivity(intent); 


一 般 来 说 ， 用户 可 以 从 可 用 的 锁 屏 机 制 中 任 选 一 个 ， 例 如 “无 >、“ 图 案 *"、“PIN 码 ”( 数 字 ) RB 
码 (字母 数字 ) 。 当 一 个 密码 策略 配置 好 后 ， 那 些 比 已 定义 密码 策略 弱 的 密码 会 被 禁用 。 此 
如 ， 如 果 配 置 了 密码 级 别 为 “Numeric”， 那 么 用 户 只 可 以 选择 PIN 码 (数字) 或 者 密码 (字母 
ET) 

一 旦 设备 通过 设置 适当 的 锁 屏 密码 处 于 被 保护 的 状态 ， 应 用 程序 便 允 许 访 问 受 保护 的 内 容 。 


if (!mDPM.isAdminActive(..)) { 


// Activates device administrator. 


) eise if (!mDPM.isActivePasswordSufficient()) 1 


// Launches password set-up screen in Settings. 


y elise f 


// Grants access to secure content. 


startActivity(new Intent(context, SecureActivity.class)); 


使 用 设备 管理 条 例 增强 安全 性 
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编写 :kesenhoo - /$ x-:http://developer.android.com/training/testing.html 


These classes and articles provide information about how to test your Android application. 


Testing Your Activity 


How to test Activities in your Android applications. 


测试 你 的 Activity 


编写 :huanglizhuo - 原文 :http://developer.android.com/training/activity-testing/index.html 


我 们 应 该 把 编写 和 运行 测试 作为 Android 应 用 开发 周期 的 一 部 分 。 完 备 的 测试 可 以 帮助 我 们 在 
开发 过 程 中 尽早 发 现 漏洞 ， 并 让 我 们 对 自己 的 代码 更 有 信心 。 


测试 用 例 定义 了 一 系列 对 象 和 方法 从 而 独立 进行 多 个 测试 。 测 试用 例 可 以 编写 成 测试 组 并 按 
计划 的 运行 ， 由 测试 框架 组 织 成 一 个 可 以 重复 运行 的 测试 Runner (运行 器 ， 译 者 注 ) © 


这 节 内 容 将 会 讲解 如 何 基于 最 流行 的 JUnit 框 架 来 自 定义 测试 框架 。 我 们 可 以 编写 测试 用 例 来 
测试 我 们 应 用 程序 的 特定 行为 ， 并 在 不 同 的 Android 设 备 上 检测 一 致 性 。 测 试用 例 还 可 以 用 来 
描述 应 用 组 件 的 预期 行为 ， 并 作为 内 部 代码 文档 。 


课程 

。 建立 测试 环境 

学 习 如 何 创建 测试 项 目 
。 创建 与 执行 测试 用 例 


学 习 如 何 写 测 试用 例 来 检验 Activity 中 的 特性 ， 并 使 用 Android 框 架 提 供 的 Instrumentation 运 行 
用 例 。 


e 测试 Ul 组件 

学 习 如 何 编写 UI 测试 用 例 
e 创建 单元 测试 

学 习 如 何 隔 离开 Activity 执 行 单元 测试 
e 创建 功能 测试 


学 习 如 何 执行 功能 测试 来 检验 各 Activity 之 间 的 交互 


建立 测试 环境 


编写 :huanglizhuo - 原文 :http://developer.android.com/training/activity-testing/preparing- 
activity-testing.html 


在 开始 编写 并 运行 我 们 的 测试 之 前 ， 我 们 应 该 建立 测试 开发 环境 。 本 小 节 将 会 讲解 如 何 建立 
Eclipse IDE 来 构建 和 运行 我 们 的 测试 ， 以 及 怎样 用 Gradle 构 建 工具 在 命令 行 下 构建 和 运行 我 
们 的 测试 。 


注意 : 本 小 节 基 于 的 是 Eclipse 及 ADT 插 件 。 然 而 ， 你 在 自己 测试 开发 时 可 以 自由 选用 IDE 


用 Eclipse 建立 测试 


安装 了 Android Developer Tools (ADT) 播 件 的 Eclipse 将 为 我 们 创建 ， 构 建 ， 以 及 运行 Android 
程序 提供 一 个 基于 图 形 界面 的 集成 开发 环境 。Eclipse 可 以 自动 为 我 们 的 Android 应 用 项 目 创建 
一 个 对 应 的 测试 项 目 。 


开始 在 Eclipse 中 创建 测试 环境 


1. 如 果 还 没 安装 Eclipse ADT 插 件 ， 请 先 下 载 安装 。 

2， 导 入 或 创建 我 们 想 要 测试 的 Android 应 用 项 目 。 

3， 生 成 一 个 对 应 于 应 用 程序 项 目测 试 的 测试 项 目 。 为 导入 项 目 生成 一 个 测试 项 目 : a. 在 项 目 
浏览 器 里 ， 右 击 我 们 的 应 用 项 目 ， 然 后 i Eo pia Tools > New Test Project b. 在 新 建 
Android 测 试 项 目 面板 ， 为 我 们 的 测试 项 目 设置 合适 的 参数 ， 然 后 点 击 Finish 


Mann 该 可 以 在 Eclipse 环境 中 创建 ， 构 建 和 运行 测试 项 目 了 。 想 要 继续 学 习 如 何在 Eclipse 中 
进行 这 些 任 务 ， 可 以 阅读 创建 与 执行 测试 用 例 


用 命令 行 建立 测试 
如 果 正 在 使 用 Gradle version 1.6 或 者 更 高 的 版 本 作为 构建 工具 ， 可 以 用 Gradle Wrapper 创 


建 。 构 建 和 运行 Android 应 用 测试 。 确 保 在 gradle.build 文件 中 ， defaultconfig 部 分 中 的 
minSdkVersion 属 性 是 8 或 更 高 。 可 以 参考 包含 在 下 载 包 中 的 示例 文件 gradle.build 


用 Gradle Wrapper 运 行 测试 : 


3& d Android Á Ju S FB Android2 44 S. o 


2. 在 项 目 目录 运行 如 下 命令 : 
./gradlew build connectedCheck 
进一步 学 习 Gradle 关 于 Android 测 试 的 内 容 ， 参 看 Gradle Plugin User Guide ° 


步 学 习 使 用 Gradle 及 其 它 命令 行 工 具 ， 参 看 Testing from Other IDEs. ° 


进 一 
本 节 示 例 代 码 AndroidTestingFun.zip 
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创建 与 执行 测试 用 例 


编写 :huanglizhuo - 原文 :http://developer.android.com/training/activity-testing/activity- 
basic-testing.html 


为 了 验证 应 用 的 布局 设计 和 功能 是 否 符合 预期 ， 为 应 用 的 每 个 Activity 建 立 测 试 非常 重要 。 对 

于 每 一 个 测试 ， 我 们 需要 在 测试 用 例 中 创建 一 个 个 独立 的 部 分 ， 包 括 测试 数据 ， 前 提 条 件 和 

ASINI 测试 方法 。 之 后 我 们 就 可 以 运行 测试 并 得 到 测试 报告 。 如 果 有 任何 测试 没有 通过 
这 表明 在 我 们 代码 中 可 能 有 潜在 的 缺陷 


Die phus 方法 中 , 不 推荐 先 编写 大 部 分 或 整个 应 用 ， 并 在 开发 完成 
后 再 运行 测试 。 而 是 应 该 先 编写 测试 ， 然 后 及 时 编写 正确 的 代码 ， 以 通过 测试 。 通 过 更 


de < ， 并 以 此 反复 。 


创建 一 个 测试 用 例 
Activity 测 试 都 是 结构 化 的 方式 编写 的 。 请 务必 把 测试 代码 放 在 一 个 单独 的 包 内 ， 从 而 与 
被 测 试 的 代码 > 


按照 惯例 ， 测 试 包 的 名 称 应 该 遵循 与 应 用 包 名 相同 的 命名 方式 ， 在 应 用 包 名 后 接 “.tests”。 在 
创建 的 测试 包 中 ， 为 我 们 的 测试 用 例 添 加 Java 类 。 按 照 惯例 ， 测 试用 例 名 称 也 应 遵循 要 测试 
的 Java 或 Android 的 类 相同 的 名 称 ， 并 增加 后 级“Test”。 


要 在 Eclipse 中 创建 一 个 新 的 测试 用 例 可 遵循 如 下 步骤 : 
a. 在 Package Explorer 中 ， 右 键 点 击 待 测试 工程 的 src/ 文 件 夹 ，New > Package 。 


b. 设置 文件 夹 名 称 < 你 的 包 名 称 >.tests (reta, com.example.android.testingfun.tests ) 并 点 
击 Finish 。 


c. 右键 点 击 创建 的 测试 包 ， 并 选择 New > Calss。 


d. 设置 文件 名 称 < 你 的 Activity 名 称 >Test (比如 ，MyFirstTestActivityTest ) ， 然 后 点 击 
Finish ° 


建立 测试 数据 集 (Fixture) 


测试 数据 集 包 含 运行 测试 前 必须 生成 的 一 些 对 象 。 要 建立 测试 数据 集 ， 可 以 在 我 们 的 测试 中 
履 写 setUp() 和 tearDown() 方 法 。 测 试 会 在 运行 任何 其 ona dot CM dal 
我 们 可 以 用 这 些 方法 使 得 被 测试 代码 与 测试 初始 化 和 清理 是 分 开 的 。 


在 你 的 Eclipse 中 建立 测试 数据 集 : 


1 .在 Package Explorer 中 双击 测试 打开 之 前 编写 的 测试 用 例 ， 然 后 修改 测试 用 例 使 它 继 
承 ActivityTestCase 的 子 类 。 比 如 : 


public class MyFirstTestActivityTest 
extends ActivityInstrumentationTestCase2«MyFirstTestActivity» { 


2 .下 一 步 ， 给 测试 用 例 添加 构造 函数 和 setUp() 方 法 ， 并 为 我 们 想 测试 的 Activity 添 加 变量 声 
明 。 比 如 : 


public class MyFirstTestActivityTest 
extends ActivityInstrumentationTestCase2«MyFirstTestActivity» { 


private MyFirstTestActivity mFirstTestActivity; 
private TextView mFirstTestText; 


public MyFirstTestActivityTest() { 
super(MyFirstTestActivity.class); 


@Override 
protected void setUp() throws Exception { 
super.setUp(); 
mFirstTestActivity = getActivity(); 
mFirstTestText = 
(TextView) mFirstTestActivity 
.findViewById(R.id.my first test text view); 





构造 函数 是 由 测试 用 的 Runner 调 用 ， 用 于 初始 化 测试 类 的 ， 而 setUp() 方 法 是 由 测试 Runner 在 
其 他 测试 方法 开始 前 运行 的 。 
通常 在 setup() 方法 中 ， 我 们 应 该 : 
e 为 setup) 调用 父 类 构造 函数 ， 这 是 JUnit 要 求 的 。 
e 初始 化 测试 数据 集 的 状态 ， 具 体 而 言 : 
o 定义 保存 测试 数据 及 状态 的 实例 变量 
o 创建 并 保存 正在 测试 的 Activity 的 引用 实例 。 
o 获得 想 要 测试 的 Activity 中 任何 Ul 组 件 的 引用 。 


我 们 可 以 使 用 getActivity() 方 法 得 到 正在 测试 的 Activity 的 引用 。 


增加 一 个 测试 前 提 


我 们 最 好 在 执行 测试 之 前 ， 检 查 测 试 数据 集 的 设置 是 否 正确 ， 以 及 我 们 想 要 测试 的 对 象 是 否 
已 经 正确 地 初始 化 。 这 样 ， 测 试 就 不 会 因为 有 测试 数据 集 的 设置 错误 而 失败 。 按 照 惯 例 ， 验 
证 测试 数据 集 的 方法 被 称 为 testPreconditions() 。 


例如 ， 我 们 可 能 想 添加 一 个 像 这 样 的 testPreconditons() 方法 : 


public void testPreconditions() { 
assertNotNull(“mFirstTestActivity is null", mFirstTestActivity); 
assertNotNull(“mFirstTestText is null", mFirstTestText); 


Assertion (断言 ， 译 者 注 ) 方法 源 自 于 JunitAssert 类 。 通 常 ， 我 们 可 以 使 用 断言 来 验证 某 一 
特定 的 条 件 是 否 是 真 的 。 


© 如 果 条 件 为 假 ， 断 言 方法 抛 出 一 个 AssertionFailedError 异 常 ， 通 常会 由 测试 Runner 报 
告 。 我 们 可 以 在 断言 失败 时 给 断言 方法 添加 一 个 字符 串 作 为 第 一 个 参数 从 而 给 出 一 些 上 
下 文 详细 信息 。 

e WRAHA BA ， 测 试 通过 。 


在 这 两 种 情况 下 ，Runner 都 会 继续 运行 其 它 测 试用 例 的 测试 方法 。 


添加 一 个 测试 方法 来 验证 Activity 


下 一 步 ， 添 加 一 个 或 多 个 测试 方法 来 验证 Activity 布 局 和 功能 。 


例如 ， 如 果 我 们 的 Activity 含 有 一 个 TextView， 可 以 添加 如 下 方法 来 检查 它 是 否 有 正确 的 标签 
文本 : 


public void testMyFirstTestTextView labelText() { 
final String expected = 
mFirstTestActivity.getString(R.string.my first test); 
final String actual - mFirstTestText.getText().toString(); 
assertEquals(expected, actual); 


该 testMyFirstTestTextView labelText() 方法 只 是 简单 的 检查 Layout 中 TextView 的 默认 文本 
是 否 和 strings.xml 资源 中 定义 的 文本 一 样 。 


注意 : 当 命名 测试 方法 时 ， 我 们 可 以 使 用 下 划 线 将 被 测试 的 内 容 与 测试 用 例 区 分 开 。 这 
种 风格 使 得 我 们 可 以 更 容易 分 清 哪些 是 测试 用 例 。 


做 这 种 类 型 的 字符 串 比 较 时 ， 推 荐 从 资源 文件 中 读 取 预 期 字符 串 ， 而 不 是 在 代码 中 硬性 编写 
字符 串 做 比较 。 这 可 以 防止 当 资 源 文件 中 的 字符 串 定 义 被 修改 时 ， 会 影响 到 测试 的 效果 。 


为 了 进行 比较 ， 预 期 的 和 实际 的 字符 串 都 要 做 为 assertEquals() 方 法 的 参数 。 如 果 值 是 不 一 样 
的 ， 断 言 将 抛 出 一 个 AssertionFailedError 异 常 。 


如 果 添 加 了 一 个 testPreconditions() 方法 , AT 可 以 把 测 试 方法 放 在 testPreconditions 之 
后 。 


要 参看 一 个 完整 的 测试 案例 ， 可 以 参考 本 节 示 例 中 的 MyFirstTestActivityTestjava 。 


构建 和 运行 测试 


我 们 可 以 在 Eclipse 中 的 包 浏 览 器 〈《Package Explorer) 中 运行 我 们 的 测试 。 
利用 如 下 步骤 构建 和 运行 测试 : 


1. 连接 一 个 Android 设 备 ， 在 设备 或 模拟 器 中 ， 打 开设 置 菜单 ， 选 择 开 发 者 选项 并 确保 启用 
USB 调 试 。 


2. 在 包 浏 览 器 (Package Explorer) 中 ， 右 键 单 击 测试 类 ， 并 选择 Run As > Android Junit 
Test ° 


3. 在 Android 设 备 选择 对 话 框 ， 选 择 刚 才 连 接 的 设备 ， 然 后 单 击 “ 确 定 ”。 
4. 在 JUnit 视 图 ， 验 证 测试 是 否 通过 ,有 无 错误 或 失败 。 


本 节 示 例 代 码 AndroidTestingFun.zip 


测试 UI 组 件 


编写 :huanglizhuo - 原文 :http://developer.android.com/training/activity-testing/activity-ui- 
testing.html 


通常 情况 下 ，Activity， 包 括 用 户 界面 组 件 (如 按钮 ， 复 选 框 ， 可 编辑 的 文本 域 ， 和 选 框 ) 允 
许 用 户 与 Android 应 用 程序 交互 。 本 节 介 绍 如 何 对 一 个 简单 的 带 有 按钮 的 界面 交互 测试 。 我 们 
可 以 使 用 相同 的 步骤 来 测试 其 他 更 复杂 的 UI 组 件 。 


注意 ; 这 一 节 的 测试 方法 叫做 白 盒 测试 ， 因 为 我 们 拥有 要 测试 应 用 程序 的 源码 。Android 
Instrumentation 框 架 适 用 于 创建 应 用 程序 中 UI 部 件 的 白 鳃 测试 。 用 户 界 面 测试 的 另 一 种 
类 型 是 黑 盒 测试 ， 即 无 法 得 知 应 用 程序 源 代码 的 类 型 。 这 种 类 型 的 测试 可 以 用 来 测试 应 
用 程序 如 何 与 其 他 应 用 程序 ， 或 与 系统 进行 交互 。 黑 盒 测试 不 包括 在 本 节 中 。 了 解 更 多 
关于 如 何在 你 的 Android 应 用 程序 进行 黑 盒 测试 ， 请 阅读 Ul Testing guide ° 


BEA REN MAR ， 可 以 查看 本 节 示 例 代 码 中 的 ClickFunActivityTest.java 文件 。 


使 用 Instrumentation 建立 UI 测试 


当 测 试 拥 有 UI 的 Activity 时 ， 被 测试 的 Activity 在 UI 线程 中 运行 。 然 而 ， 测 试 程序 会 在 程序 自己 
的 进程 中 ， 单 独 的 一 个 线程 内 运行 。 这 意味 着 ， 我 们 的 测试 程序 可 以 获得 Ul 线 程 的 对 象 ， 但 
是 如 果 它 尝试 改变 UI 线 程 对 象 的 值 ， 会 得 到 wrongThreadException 错误 。 

为 了 安全 地 将 Intent 注入 到 Activity ， 或 是 在 UI 线 程 中 执行 测试 方法 ， 我 们 可 以 让 测试 类 


继承 于 ActivitylnstrumentationTestCase2。 要 学 习 如 何在 UI 线 程 运 行 测试 方法 ， 请 看 在 UI 线 程 
测试 。 


建立 测试 数据 集 (Fixture ) 


当 为 UI 测试 建立 测试 数据 集 时 ， 我 们 应 该 在 setUp() 方 法 中 指定 touch mode。 把 touch mode 设 
置 为 监 可 以 防止 在 执行 编写 的 测试 方法 时 ， 人 为 的 UI 操作 获取 到 控件 的 焦点 (比如 ,一 个 按 鱼 
会 触发 它 的 点 击 监 听 器 ) 。 确 保 在 调用 getActivity() 方 法 前 调用 了 

setActivityInitialTouchMode) ° 


比如 : 


public class ClickFunActivityTest 
extends ActivityInstrumentationTestCase2 { 


@Override 
protected void setUp() throws Exception { 
super.setUp(); 


setActivityInitialTouchMode(true); 


mClickFunActivity - getActivity(); 

mClickMeButton - (Button) 
mClickFunActivity 
.findViewById(R.id.launch next activity button); 

mInfoTextView - (TextView) 
mClickFunActivity.findViewById(R.id.info text view); 


添加 测试 方法 确认 UI 响应 表现 


UI 测试 目标 应 包括 : 


. 检验 Activity 启 动 时 Button 在 正确 布局 位 置 显示 。 . 检验 TextView 初 始 化 时 是 隐藏 的 。*. 检验 
TextView 在 Button 点 击 时 显示 预期 的 字符 串 


接 下 来 的 部 分 会 演示 怎样 实现 上 述 验证 方法 


难 证 Button 布 局 参数 
我 们 应 该 像 如 下 添加 的 测试 方法 那样 。 验 证 Activity 中 的 按钮 是 否 正确 显示 : 


@MediumTest 
public void testClickMeButton_layout() { 
final View decorView = mClickFunActivity.getWindow().getDecorView(); 


ViewAsserts.assertOnScreen(decorView, mClickMeButton) ; 


final ViewGroup.LayoutParams layoutParams = 
mClickMeButton.getLayoutParams(); 

assertNotNull(layoutParams); 

assertEquals(layoutParams.width, WindowManager.LayoutParams.MATCH PARENT); 

assertEquals(layoutParams.height, WindowManager.LayoutParams.WRAP CONTENT); 


在 调用 assertOnScreen() 方 法 时 ， 传 递 根 视图 以 及 期 望 呈 现在 屏幕 上 的 视图 作为 参数 。 如 果 想 
呈现 的 视图 没有 在 根 视图 中 ,该 方法 会 抛 出 一 个 AssertionFailedError 异 常 ， 否 则 测试 通过 。 


我 们 也 可 以 通过 获取 一 个 ViewGroup. LayoutParams 对 象 的 引 用 验证 Button 布 局 是 否 正 确 ， 然 
后 调用 assert 方法 验证 Button 对 象 的 宽 高 属性 值 是 否 与 预期 值 一 致 。 


@MediumTest 注解 指定 测试 是 如 何 归 类 的 (和 它 的 执行 时 间 相 关 ) 。 要 了 解 更 多 有 关 测 试 的 注 
解 ， 见 本 节 示 例 。 


验证 TextView 的 布局 参数 
可 以 像 这 样 添加 一 个 测试 方法 来 验证 TextView 最 初 是 隐藏 在 Activity 中 的 : 


@MediumTest 

public void testInfoTextView_layout() { 
final View decorView = mClickFunActivity.getWindow().getDecorView(); 
ViewAsserts.assertOnScreen(decorView, mInfoTextView) ; 
assertTrue(View.GONE == mInfoTextView.getVisibility()); 


我 们 可 以 调用 getdecorview() 方法 得 到 一 个 Activity 中 修饰 试图 (Decor View) 的 引用 。 要 修 
饰 的 View 在 布局 层次 视图 中 是 最 上 层 的 ViewGroup(FrameLayout) 


验证 按钮 的 行为 
可 以 使 用 如 下 测试 方法 来 验证 当 按 下 按钮 时 TextView 变 得 可 见 : 


@MediumTest 

public void testClickMeButton clickButtonAndExpectInfoText() { 
String expectedInfoText - mClickFunActivity.getString(R.string.info text); 
TouchUtils.clickView(this, mClickMeButton); 
assertTrue(View.VISIBLE -- mInfoTextView.getVisibility()); 
assertEquals(expectedInfoText, mInfoTextView.getText()); 


在 测试 中 调用 clickView() 可 以 让 我 们 用 编程 方式 点 击 一 个 按钮 。 我 们 必须 传递 正在 运行 的 测试 
用 例 的 一 个 引用 和 要 操作 按钮 的 引用 。 


注意 :TouchUtils 辅 助 类 提供 与 应 iin 多 交互 的 方法 可 以 方便 进行 模拟 触摸 操作 。 我 们 可 
以 使 用 这 些 方 法 来 模拟 点 击 ， 轻 敲 ， 或 应 用 程序 屏幕 拖 动 View。 


警告 TouchUtils 方 法 的 目的 是 将 事件 安全 地 从 测试 线程 发 送 到 UI 线 程 。 我 们 不 可 以 直接 在 
UI 线 程 或 任何 标注 @UIThread 的 测试 方法 中 使 用 TouchUtils 这 样 做 可 能 会 增加 错误 线程 异 
常 o 


应 用 测试 注解 


@SmallTest 


标志 该 测试 方法 是 小 型 测试 的 一 部 分 。 


@MediumTest 


标志 该 测试 方法 是 中 等 测试 的 一 部 分 。 


@LargeTest 


标志 该 测试 方法 是 大 型 测试 的 一 部 分 。 


通常 情况 下 ， 如 果 测 试 方法 只 需要 几 毫 秒 的 时 间 ， 那 么 它 应 该 被 标记 为 @SmallTest， 长 时 间 
运行 的 测试 (100 毫 秒 或 更 多 ) 通常 被 标记 为 @MediumTest 或 @LargeTest， 这 主要 取决 于 测 
试 访问 资源 在 网 络 上 或 在 本 地 系统 。 可 以 参看 Android Tools Protip， 它 可 以 更 好 地 指导 我 们 
使 用 测试 注释 


我 们 可 以 创建 其 它 的 测试 注释 来 控制 测试 的 组 织 和 运行 。 要 了 解 更 多 关于 其 他 注释 的 信息 ， 
见 Annotation 类 参考 。 


本 节 示 例 代 码 AndroidTestingFun.zip 


创建 单元 测试 


编写 :huanglizhuo - 原文 :http://developer.android.com/training/activity-testing/activity- 
unit-testing.html 
Activity 单 元 测试 可 以 快速 且 独 立地 (和 系统 其 它 部 分 分 离 ) 验证 一 个 Activity 的 状态 以 及 其 与 
其 它 组 件 交 互 的 正确 性 。 一 个 单元 测试 通常 用 来 测试 代码 中 最 小 单位 的 代码 块 (可 以 是 一 个 
方法 ， 类 ， 或 者 组 件 ) ， 而 且 也 不 依赖 于 系统 或 网 络 资源 。 比 如 说 ， 你 可 以 写 一 个 单元 测试 
去 检查 Activity 是 否 正确 地 布局 或 者 是 否 可 以 正确 地 触发 一 个 Intent 对 象 。 


单元 测试 一 般 不 适合 测试 与 系统 有 复杂 交互 的 Ul。 我 们 应 该 使 用 如 同 测试 Ul 组 件 所 描述 
的 ActivityInstrumentationTestCase2 来 对 这 类 UI 交互 进行 测试 。 
这 节 内 容 将 会 讲解 如 何 编写 一 个 单元 测试 来 验证 一 个 Intent 是 否 正确 地 触发 了 另 一 个 Activity » 
由 于 测试 是 与 环境 独立 的 ， 所 以 Intent 实 际 上 并 没有 发 送 给 Android 系 统 ， 但 我 们 可 以 检查 
Intent 对 象 的 载荷 数据 是 否 正 确 。 读 者 可 以 参考 一 下 示例 代码 中 的 LaunchactivityTest.java ， 
将 它 作为 一 个 例子 ， 了 解 完 备 的 测试 用 例 是 怎么 样 的 。 
注意 : 如 果 要 针对 系统 或 者 外 部 依赖 进行 测试 ， 我 们 可 以 使 用 Mocking Framework 的 
Mock 类 ， 并 把 它 集成 到 我 们 的 你 的 单元 测试 中 。 要 了 解 更 多 关于 Android 提 供 的 Mocking 
Framework 内 容 请 参考 Mock Object Classes。 


编写 一 个 Android 单 元 测试 例子 


ActiviUnitTestCase 类 提供 对 于 单个 Activity 进 行 分 离 测 试 的 支持 。 要 创建 单元 测试 ， 我 们 的 测 
试 类 应 该 继承 自 activiunittestCase 。 继 承 ActiviunitTestcase 的 Activity 不 会 被 Android 自 动 
启动 。 要 单独 启动 Activity， 我 们 需要 显 式 的 调用 startActivity() 方 法 ， 并 传递 一 个 Intent 来 启动 
我 们 的 目标 Activity 。 


例如 : 


public class LaunchActivityTest 
extends ActivityUnitTestCase«LaunchActivity» { 


@Override 
protected void setUp() throws Exception { 
super.setUp(); 
mLaunchlIntent = new Intent(getInstrumentation() 
.getTargetContext(), LaunchActivity.class); 
startActivity(mLaunchIntent, null, null); 
final Button launchNextButton - 
(Button) getActivity() 
.findViewById(R.id.launch next activity button); 


验证 另 一 个 Activity 的 启动 


我 们 的 单元 测试 目标 可 能 包括 : 


e 验证 当 Button 被 按 下 时 ， 启 动 的 LaunchActivity 是 否 正确 。 
e 验证 启动 的 Intent 是 否 包 含有 效 的 数据 。 


为 了 验证 一 个 触发 Intent 的 Button 的 事件 ， 我 们 可 以 使 用 getStartedActivitylntent() 方 法 。 通 过 
使 用 断言 方法 ， 我 们 可 以 验证 返回 的 Intent 是 否 为 室 ， 以 及 是 否 包含 了 预期 的 数据 来 启动 下 一 
个 Activity。 如 果 两 个 断言 值 都 是 览 ， 那 么 我 们 就 成 功 地 验证 了 Activity 发 送 的 Intent 是 正确 的 
了 。 


我 们 可 以 这 样 实现 测试 方法 : 


@MediumTest 
public void testNextActivityWasLaunchedwithIntent() { 
startActivity(mLaunchIntent, null, null); 
final Button launchNextButton - 
(Button) getActivity() 
.findViewById(R.id.launch next activity button); 
launchNextButton.performClick(); 


final Intent launchIntent - getStartedActivityIntent(); 
assertNotNull("Intent was null", launchIntent); 
assertTrue(isFinishCalled()); 


final String payload - 
launchIntent.getStringExtra(NextActivity.EXTRAS PAYLOAD KEY); 
assertEquals("Payload is empty", LaunchActivity.STRING PAYLOAD, payload); 


为 LaunchActivity 是 独立 运行 的 ， 所 以 不 可 以 使 用 TouchUtils 库 来 操作 UI。 如 果 要 直接 进 
行 Button 上 点击， 我 们 可 以 调用 perfoemClick() 方 法 。 


本 节 示 例 代 码 AndroidTestingFun.zip 
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编写 :huanglizhuo - 原文 :http://developer.android.com/training/activity-testing/activity- 
functional-testing.html 


功能 测试 包括 验证 单个 应 用 中 的 各 个 组 件 是 否 与 使 用 者 期 望 的 那样 〈 与 其 它 组 件 ) 协同 工 
作 。 比 如 ， 我 们 可 以 创建 一 个 功能 测试 验证 在 用 户 执行 Ul 交 互 时 Activity 是 否 正 确 局 动 目 
4% Activity ° 


要 为 Activity 创 建功 能 测 ， 我 们 的 测试 类 应 该 对 ActivityInstrumentationTestCase2 进 行 扩 展 。 
与 ActivityUnitTestCase 不 同 ，ActivitylnstrumentationTestCase2 中 的 测试 可 以 与 Android 系 统 
通信 ， 发 送 键盘 输入 及 点 击 事件 到 Ul 中 。 


要 了 解 一 个 完整 的 测试 例子 可 以 参考 示例 应 用 中 的 SenderActivityTest.java ? 


添加 测试 方法 验证 函数 的 行为 


我 们 的 函数 测试 目标 应 该 包括 : 


e 验证 UI 控制 是 否 正 确 启动 了 目标 Activity。 
e 验证 目标 Activity 的 表现 是 否 按 照发 送 Activity 提 供 的 数据 呈现 。 


我 们 可 以 这 样 实现 测试 方法 : 


@MediumTest 
public void testSendMessageToReceiverActivity() { 
final Button sendToReceiverButton - (Button) 
mSenderActivity.findViewById(R.id.send message button); 


final EditText senderMessageEditText - (EditText) 
mSenderActivity.findViewById(R.id.message input edit text); 


// Set up an ActivityMonitor 

// Send string input value 

// Validate that ReceiverActivity is started 

// Nalidate that ReceiverActivity has the correct data 


// Remove the ActivityMonitor 


测试 会 等 待 匹 配 的 Activity 启 动 ， 如 果 超 时 则 会 返回 null。 如 果 ReceiverActivity 启 动 了 ， 那 么 先 
前 配置 的 ActivityMoniter 就 会 收 到 一 次 碰撞 (Hit) 。 我 们 可 以 使 用 断言 方法 验证 
ReceiverActivity 是 否 的 确 启 动 了 ， 以 及 ActivityMoniter 记 录 的 碰撞 次 数 是 否 按照 预想 地 那样 增 
Jm? 


iz 3L — ^ ActivityMonitor 


为 了 在 应 用 中 监视 单个 Activity 我 们 可 以 注册 一 个 ActivityMoniter。 每 当 一 个 符合 要 求 的 Activity 
启动 时 ， 系 统 会 通知 ActivityMoniter， 进 而 更 新 碰撞 数目 。 


常 来 说 要 使 用 ActivityMoniter， 我 们 可 以 这 样 : 


一 人 


使 用 getlnstrumentation() 方 法 为 测试 用 例 实 现 Instrumentation。 

使 用 Instrumentation 的 一 种 addMonitor() 方 法 为 当前 instrumentation 添 加 一 

ngantation ActivityMonitor 实 例 。 匹 配 规则 可 以 通过 IntentFilter 或 者 类 名 字符 串 。 
等 待 开 启 一 个 Activity 。 

4. 验证 监视 器 撞击 次 数 的 增加 。 

5， 移 除 监 视 器 。 


N 


e 


下 面 是 一 个 例子 : 


// Set up an ActivityMonitor 

ActivityMonitor receiverActivityMonitor - 
getInstrumentation().addMonitor(ReceiverActivity.class.getName(), 
null, false); 


// Nalidate that ReceiverActivity is started 
TouchUtils.clickView(this, sendToReceiverButton); 
ReceiverActivity receiverActivity - (ReceiverActivity) 
receiverActivityMonitor.waitForActivityWithTimeout(TIMEOUT IN MS); 
assertNotNull("ReceiverActivity is null", receiverActivity); 
assertEquals("Monitor for ReceiverActivity has not been called", 
1, receiverActivityMonitor.getHits()); 
assertEquals("Activity is of wrong type", 
ReceiverActivity.class, receiverActivity.getClass()); 


// Remove the ActivityMonitor 
getInstrumentation().removeMonitor(receiverActivityMonitor); 
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如 果 Activity 有 一 个 EditText， 我 们 可 以 测试 用 户 是 否 可 以 给 EditText 对 象 输 入 数值 。 
通常 在 Activitylnstrumentation TestCase2 中 给 EditText 对 象 发 送 串 字 符 ， 我 们 可 以 这 样 做 : 


1. 使 用 runOnMainSync() 方 法 在 一 个 循环 中 同步 地 调用 redquestFocus()。 这 样 ， 我 们 的 UI 线 
程 就 会 在 获得 焦点 前 一 直 被 阻塞 。 
2. 调用 waitForldleSync() 方 法 等 待 主线 程 空闲 (也 就 是 说 ,没有 更 


多 要 处 理 ) 。 
3. 调用 sendStringSync() 方 法 给 EditText 对 象 发送 一 个 我 们 输入 的 字 


事件 需 
A 
比如 : 


// Send string input value 
getInstrumentation().runOnMainSync(new Runnable() { 
@Override 
public void run() { 
senderMessageEditText.requestFocus(); 


1 

getInstrumentation().waitForIdleSync(); 
getInstrumentation().sendStringSync("Hello Android!"); 
getInstrumentation().waitForIdleSync(); 


本 节 例 子 AndroidTestingFun.zip 
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